This is /home/cyd/emacs/doc/lispref/../../info/elisp, produced by
makeinfo version 4.13 from /home/cyd/emacs/doc/lispref/elisp.texi.

This is the `GNU Emacs Lisp Reference Manual' corresponding to Emacs
version 24.2.

Copyright (C) 1990-1996, 1998-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "GNU General Public
     License," with the Front-Cover texts being "A GNU Manual," and
     with the Back-Cover Texts as in (a) below.  A copy of the license
     is included in the section entitled "GNU Free Documentation
     License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION GNU Emacs Lisp
START-INFO-DIR-ENTRY
* Elisp: (elisp).       The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY


File: elisp,  Node: Format Conversion Round-Trip,  Next: Format Conversion Piecemeal,  Prev: Format Conversion Overview,  Up: Format Conversion

25.12.2 Round-Trip Specification
--------------------------------

The most general of the two facilities is controlled by the variable
`format-alist', a list of "file format" specifications, which describe
textual representations used in files for the data in an Emacs buffer.
The descriptions for reading and writing are paired, which is why we
call this "round-trip" specification (*note Format Conversion
Piecemeal::, for non-paired specification).

 -- Variable: format-alist
     This list contains one format definition for each defined file
     format.  Each format definition is a list of this form:

          (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN PRESERVE)

Here is what the elements in a format definition mean:

NAME
     The name of this format.

DOC-STRING
     A documentation string for the format.

REGEXP
     A regular expression which is used to recognize files represented
     in this format.  If `nil', the format is never applied
     automatically.

FROM-FN
     A shell command or function to decode data in this format (to
     convert file data into the usual Emacs data representation).

     A shell command is represented as a string; Emacs runs the command
     as a filter to perform the conversion.

     If FROM-FN is a function, it is called with two arguments, BEGIN
     and END, which specify the part of the buffer it should convert.
     It should convert the text by editing it in place.  Since this can
     change the length of the text, FROM-FN should return the modified
     end position.

     One responsibility of FROM-FN is to make sure that the beginning
     of the file no longer matches REGEXP.  Otherwise it is likely to
     get called again.

TO-FN
     A shell command or function to encode data in this format--that
     is, to convert the usual Emacs data representation into this
     format.

     If TO-FN is a string, it is a shell command; Emacs runs the
     command as a filter to perform the conversion.

     If TO-FN is a function, it is called with three arguments: BEGIN
     and END, which specify the part of the buffer it should convert,
     and BUFFER, which specifies which buffer.  There are two ways it
     can do the conversion:

        * By editing the buffer in place.  In this case, TO-FN should
          return the end-position of the range of text, as modified.

        * By returning a list of annotations.  This is a list of
          elements of the form `(POSITION . STRING)', where POSITION is
          an integer specifying the relative position in the text to be
          written, and STRING is the annotation to add there.  The list
          must be sorted in order of position when TO-FN returns it.

          When `write-region' actually writes the text from the buffer
          to the file, it intermixes the specified annotations at the
          corresponding positions.  All this takes place without
          modifying the buffer.

MODIFY
     A flag, `t' if the encoding function modifies the buffer, and
     `nil' if it works by returning a list of annotations.

MODE-FN
     A minor-mode function to call after visiting a file converted from
     this format.  The function is called with one argument, the
     integer 1; that tells a minor-mode function to enable the mode.

PRESERVE
     A flag, `t' if `format-write-file' should not remove this format
     from `buffer-file-format'.

   The function `insert-file-contents' automatically recognizes file
formats when it reads the specified file.  It checks the text of the
beginning of the file against the regular expressions of the format
definitions, and if it finds a match, it calls the decoding function for
that format.  Then it checks all the known formats over again.  It
keeps checking them until none of them is applicable.

   Visiting a file, with `find-file-noselect' or the commands that use
it, performs conversion likewise (because it calls
`insert-file-contents'); it also calls the mode function for each
format that it decodes.  It stores a list of the format names in the
buffer-local variable `buffer-file-format'.

 -- Variable: buffer-file-format
     This variable states the format of the visited file.  More
     precisely, this is a list of the file format names that were
     decoded in the course of visiting the current buffer's file.  It
     is always buffer-local in all buffers.

   When `write-region' writes data into a file, it first calls the
encoding functions for the formats listed in `buffer-file-format', in
the order of appearance in the list.

 -- Command: format-write-file file format &optional confirm
     This command writes the current buffer contents into the file FILE
     in a format based on FORMAT, which is a list of format names.  It
     constructs the actual format starting from FORMAT, then appending
     any elements from the value of `buffer-file-format' with a
     non-`nil' PRESERVE flag (see above), if they are not already
     present in FORMAT.  It then updates `buffer-file-format' with this
     format, making it the default for future saves.  Except for the
     FORMAT argument, this command is similar to `write-file'.  In
     particular, CONFIRM has the same meaning and interactive treatment
     as the corresponding argument to `write-file'.  *Note Definition
     of write-file::.

 -- Command: format-find-file file format
     This command finds the file FILE, converting it according to
     format FORMAT.  It also makes FORMAT the default if the buffer is
     saved later.

     The argument FORMAT is a list of format names.  If FORMAT is
     `nil', no conversion takes place.  Interactively, typing just
     <RET> for FORMAT specifies `nil'.

 -- Command: format-insert-file file format &optional beg end
     This command inserts the contents of file FILE, converting it
     according to format FORMAT.  If BEG and END are non-`nil', they
     specify which part of the file to read, as in
     `insert-file-contents' (*note Reading from Files::).

     The return value is like what `insert-file-contents' returns: a
     list of the absolute file name and the length of the data inserted
     (after conversion).

     The argument FORMAT is a list of format names.  If FORMAT is
     `nil', no conversion takes place.  Interactively, typing just
     <RET> for FORMAT specifies `nil'.

 -- Variable: buffer-auto-save-file-format
     This variable specifies the format to use for auto-saving.  Its
     value is a list of format names, just like the value of
     `buffer-file-format'; however, it is used instead of
     `buffer-file-format' for writing auto-save files.  If the value is
     `t', the default, auto-saving uses the same format as a regular
     save in the same buffer.  This variable is always buffer-local in
     all buffers.


File: elisp,  Node: Format Conversion Piecemeal,  Prev: Format Conversion Round-Trip,  Up: Format Conversion

25.12.3 Piecemeal Specification
-------------------------------

In contrast to the round-trip specification described in the previous
subsection (*note Format Conversion Round-Trip::), you can use the
variables `after-insert-file-functions' and
`write-region-annotate-functions' to separately control the respective
reading and writing conversions.

   Conversion starts with one representation and produces another
representation.  When there is only one conversion to do, there is no
conflict about what to start with.  However, when there are multiple
conversions involved, conflict may arise when two conversions need to
start with the same data.

   This situation is best understood in the context of converting text
properties during `write-region'.  For example, the character at
position 42 in a buffer is `X' with a text property `foo'.  If the
conversion for `foo' is done by inserting into the buffer, say, `FOO:',
then that changes the character at position 42 from `X' to `F'.  The
next conversion will start with the wrong data straight away.

   To avoid conflict, cooperative conversions do not modify the buffer,
but instead specify "annotations", a list of elements of the form
`(POSITION . STRING)', sorted in order of increasing POSITION.

   If there is more than one conversion, `write-region' merges their
annotations destructively into one sorted list.  Later, when the text
from the buffer is actually written to the file, it intermixes the
specified annotations at the corresponding positions.  All this takes
place without modifying the buffer.

   In contrast, when reading, the annotations intermixed with the text
are handled immediately.  `insert-file-contents' sets point to the
beginning of some text to be converted, then calls the conversion
functions with the length of that text.  These functions should always
return with point at the beginning of the inserted text.  This approach
makes sense for reading because annotations removed by the first
converter can't be mistakenly processed by a later converter.  Each
conversion function should scan for the annotations it recognizes,
remove the annotation, modify the buffer text (to set a text property,
for example), and return the updated length of the text, as it stands
after those changes.  The value returned by one function becomes the
argument to the next function.

 -- Variable: write-region-annotate-functions
     A list of functions for `write-region' to call.  Each function in
     the list is called with two arguments: the start and end of the
     region to be written.  These functions should not alter the
     contents of the buffer.  Instead, they should return annotations.

     As a special case, a function may return with a different buffer
     current.  Emacs takes this to mean that the current buffer contains
     altered text to be output.  It therefore changes the START and END
     arguments of the `write-region' call, giving them the values of
     `point-min' and `point-max' in the new buffer, respectively.  It
     also discards all previous annotations, because they should have
     been dealt with by this function.

 -- Variable: write-region-post-annotation-function
     The value of this variable, if non-`nil', should be a function.
     This function is called, with no arguments, after `write-region'
     has completed.

     If any function in `write-region-annotate-functions' returns with
     a different buffer current, Emacs calls
     `write-region-post-annotation-function' more than once.  Emacs
     calls it with the last buffer that was current, and again with the
     buffer before that, and so on back to the original buffer.

     Thus, a function in `write-region-annotate-functions' can create a
     buffer, give this variable the local value of `kill-buffer' in
     that buffer, set up the buffer with altered text, and make the
     buffer current.  The buffer will be killed after `write-region' is
     done.

 -- Variable: after-insert-file-functions
     Each function in this list is called by `insert-file-contents'
     with one argument, the number of characters inserted, and with
     point at the beginning of the inserted text.  Each function should
     leave point unchanged, and return the new character count
     describing the inserted text as modified by the function.

   We invite users to write Lisp programs to store and retrieve text
properties in files, using these hooks, and thus to experiment with
various data formats and find good ones.  Eventually we hope users will
produce good, general extensions we can install in Emacs.

   We suggest not trying to handle arbitrary Lisp objects as text
property names or values--because a program that general is probably
difficult to write, and slow.  Instead, choose a set of possible data
types that are reasonably flexible, and not too hard to encode.


File: elisp,  Node: Backups and Auto-Saving,  Next: Buffers,  Prev: Files,  Up: Top

26 Backups and Auto-Saving
**************************

Backup files and auto-save files are two methods by which Emacs tries
to protect the user from the consequences of crashes or of the user's
own errors.  Auto-saving preserves the text from earlier in the current
editing session; backup files preserve file contents prior to the
current session.

* Menu:

* Backup Files::   How backup files are made; how their names are chosen.
* Auto-Saving::    How auto-save files are made; how their names are chosen.
* Reverting::      `revert-buffer', and how to customize what it does.


File: elisp,  Node: Backup Files,  Next: Auto-Saving,  Up: Backups and Auto-Saving

26.1 Backup Files
=================

A "backup file" is a copy of the old contents of a file you are
editing.  Emacs makes a backup file the first time you save a buffer
into its visited file.  Thus, normally, the backup file contains the
contents of the file as it was before the current editing session.  The
contents of the backup file normally remain unchanged once it exists.

   Backups are usually made by renaming the visited file to a new name.
Optionally, you can specify that backup files should be made by copying
the visited file.  This choice makes a difference for files with
multiple names; it also can affect whether the edited file remains owned
by the original owner or becomes owned by the user editing it.

   By default, Emacs makes a single backup file for each file edited.
You can alternatively request numbered backups; then each new backup
file gets a new name.  You can delete old numbered backups when you
don't want them any more, or Emacs can delete them automatically.

* Menu:

* Making Backups::     How Emacs makes backup files, and when.
* Rename or Copy::     Two alternatives: renaming the old file or copying it.
* Numbered Backups::   Keeping multiple backups for each source file.
* Backup Names::       How backup file names are computed; customization.


File: elisp,  Node: Making Backups,  Next: Rename or Copy,  Up: Backup Files

26.1.1 Making Backup Files
--------------------------

 -- Function: backup-buffer
     This function makes a backup of the file visited by the current
     buffer, if appropriate.  It is called by `save-buffer' before
     saving the buffer the first time.

     If a backup was made by renaming, the return value is a cons cell
     of the form (MODES CONTEXT BACKUPNAME), where MODES are the mode
     bits of the original file, as returned by `file-modes' (*note
     Other Information about Files: File Attributes.), CONTEXT is a
     list describing the original file's SELinux context (*note File
     Attributes::), and BACKUPNAME is the name of the backup.  In all
     other cases, that is, if a backup was made by copying or if no
     backup was made, this function returns `nil'.

 -- Variable: buffer-backed-up
     This buffer-local variable says whether this buffer's file has
     been backed up on account of this buffer.  If it is non-`nil', the
     backup file has been written.  Otherwise, the file should be backed
     up when it is next saved (if backups are enabled).  This is a
     permanent local; `kill-all-local-variables' does not alter it.

 -- User Option: make-backup-files
     This variable determines whether or not to make backup files.  If
     it is non-`nil', then Emacs creates a backup of each file when it
     is saved for the first time--provided that `backup-inhibited' is
     `nil' (see below).

     The following example shows how to change the `make-backup-files'
     variable only in the Rmail buffers and not elsewhere.  Setting it
     `nil' stops Emacs from making backups of these files, which may
     save disk space.  (You would put this code in your init file.)

          (add-hook 'rmail-mode-hook
                    (lambda ()
                      (set (make-local-variable 'make-backup-files) nil)))

 -- Variable: backup-enable-predicate
     This variable's value is a function to be called on certain
     occasions to decide whether a file should have backup files.  The
     function receives one argument, an absolute file name to consider.
     If the function returns `nil', backups are disabled for that file.
     Otherwise, the other variables in this section say whether and how
     to make backups.

     The default value is `normal-backup-enable-predicate', which checks
     for files in `temporary-file-directory' and
     `small-temporary-file-directory'.

 -- Variable: backup-inhibited
     If this variable is non-`nil', backups are inhibited.  It records
     the result of testing `backup-enable-predicate' on the visited file
     name.  It can also coherently be used by other mechanisms that
     inhibit backups based on which file is visited.  For example, VC
     sets this variable non-`nil' to prevent making backups for files
     managed with a version control system.

     This is a permanent local, so that changing the major mode does
     not lose its value.  Major modes should not set this
     variable--they should set `make-backup-files' instead.

 -- User Option: backup-directory-alist
     This variable's value is an alist of filename patterns and backup
     directory names.  Each element looks like
          (REGEXP . DIRECTORY)

     Backups of files with names matching REGEXP will be made in
     DIRECTORY.  DIRECTORY may be relative or absolute.  If it is
     absolute, so that all matching files are backed up into the same
     directory, the file names in this directory will be the full name
     of the file backed up with all directory separators changed to `!'
     to prevent clashes.  This will not work correctly if your
     filesystem truncates the resulting name.

     For the common case of all backups going into one directory, the
     alist should contain a single element pairing `"."' with the
     appropriate directory name.

     If this variable is `nil' (the default), or it fails to match a
     filename, the backup is made in the original file's directory.

     On MS-DOS filesystems without long names this variable is always
     ignored.

 -- User Option: make-backup-file-name-function
     This variable's value is a function to use for making backups
     instead of the default `make-backup-file-name'.  A value of `nil'
     gives the default `make-backup-file-name' behavior.  *Note Naming
     Backup Files: Backup Names.

     This could be buffer-local to do something special for specific
     files.  If you define it, you may need to change
     `backup-file-name-p' and `file-name-sans-versions' too.


File: elisp,  Node: Rename or Copy,  Next: Numbered Backups,  Prev: Making Backups,  Up: Backup Files

26.1.2 Backup by Renaming or by Copying?
----------------------------------------

There are two ways that Emacs can make a backup file:

   * Emacs can rename the original file so that it becomes a backup
     file, and then write the buffer being saved into a new file.
     After this procedure, any other names (i.e., hard links) of the
     original file now refer to the backup file.  The new file is owned
     by the user doing the editing, and its group is the default for
     new files written by the user in that directory.

   * Emacs can copy the original file into a backup file, and then
     overwrite the original file with new contents.  After this
     procedure, any other names (i.e., hard links) of the original file
     continue to refer to the current (updated) version of the file.
     The file's owner and group will be unchanged.

   The first method, renaming, is the default.

   The variable `backup-by-copying', if non-`nil', says to use the
second method, which is to copy the original file and overwrite it with
the new buffer contents.  The variable `file-precious-flag', if
non-`nil', also has this effect (as a sideline of its main
significance).  *Note Saving Buffers::.

 -- User Option: backup-by-copying
     If this variable is non-`nil', Emacs always makes backup files by
     copying.  The default is `nil'.

   The following three variables, when non-`nil', cause the second
method to be used in certain special cases.  They have no effect on the
treatment of files that don't fall into the special cases.

 -- User Option: backup-by-copying-when-linked
     If this variable is non-`nil', Emacs makes backups by copying for
     files with multiple names (hard links).  The default is `nil'.

     This variable is significant only if `backup-by-copying' is `nil',
     since copying is always used when that variable is non-`nil'.

 -- User Option: backup-by-copying-when-mismatch
     If this variable is non-`nil' (the default), Emacs makes backups
     by copying in cases where renaming would change either the owner or
     the group of the file.

     The value has no effect when renaming would not alter the owner or
     group of the file; that is, for files which are owned by the user
     and whose group matches the default for a new file created there
     by the user.

     This variable is significant only if `backup-by-copying' is `nil',
     since copying is always used when that variable is non-`nil'.

 -- User Option: backup-by-copying-when-privileged-mismatch
     This variable, if non-`nil', specifies the same behavior as
     `backup-by-copying-when-mismatch', but only for certain user-id
     values: namely, those less than or equal to a certain number.  You
     set this variable to that number.

     Thus, if you set `backup-by-copying-when-privileged-mismatch' to
     0, backup by copying is done for the superuser only, when
     necessary to prevent a change in the owner of the file.

     The default is 200.


File: elisp,  Node: Numbered Backups,  Next: Backup Names,  Prev: Rename or Copy,  Up: Backup Files

26.1.3 Making and Deleting Numbered Backup Files
------------------------------------------------

If a file's name is `foo', the names of its numbered backup versions
are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
`foo.~3~', ..., `foo.~259~', and so on.

 -- User Option: version-control
     This variable controls whether to make a single non-numbered backup
     file or multiple numbered backups.

    `nil'
          Make numbered backups if the visited file already has
          numbered backups; otherwise, do not.  This is the default.

    `never'
          Do not make numbered backups.

    ANYTHING ELSE
          Make numbered backups.

   The use of numbered backups ultimately leads to a large number of
backup versions, which must then be deleted.  Emacs can do this
automatically or it can ask the user whether to delete them.

 -- User Option: kept-new-versions
     The value of this variable is the number of newest versions to keep
     when a new numbered backup is made.  The newly made backup is
     included in the count.  The default value is 2.

 -- User Option: kept-old-versions
     The value of this variable is the number of oldest versions to keep
     when a new numbered backup is made.  The default value is 2.

   If there are backups numbered 1, 2, 3, 5, and 7, and both of these
variables have the value 2, then the backups numbered 1 and 2 are kept
as old versions and those numbered 5 and 7 are kept as new versions;
backup version 3 is excess.  The function `find-backup-file-name'
(*note Backup Names::) is responsible for determining which backup
versions to delete, but does not delete them itself.

 -- User Option: delete-old-versions
     If this variable is `t', then saving a file deletes excess backup
     versions silently.  If it is `nil', that means to ask for
     confirmation before deleting excess backups.  Otherwise, they are
     not deleted at all.

 -- User Option: dired-kept-versions
     This variable specifies how many of the newest backup versions to
     keep in the Dired command `.' (`dired-clean-directory').  That's
     the same thing `kept-new-versions' specifies when you make a new
     backup file.  The default is 2.


File: elisp,  Node: Backup Names,  Prev: Numbered Backups,  Up: Backup Files

26.1.4 Naming Backup Files
--------------------------

The functions in this section are documented mainly because you can
customize the naming conventions for backup files by redefining them.
If you change one, you probably need to change the rest.

 -- Function: backup-file-name-p filename
     This function returns a non-`nil' value if FILENAME is a possible
     name for a backup file.  It just checks the name, not whether a
     file with the name FILENAME exists.

          (backup-file-name-p "foo")
               => nil
          (backup-file-name-p "foo~")
               => 3

     The standard definition of this function is as follows:

          (defun backup-file-name-p (file)
            "Return non-nil if FILE is a backup file \
          name (numeric or not)..."
            (string-match "~\\'" file))

     Thus, the function returns a non-`nil' value if the file name ends
     with a `~'.  (We use a backslash to split the documentation
     string's first line into two lines in the text, but produce just
     one line in the string itself.)

     This simple expression is placed in a separate function to make it
     easy to redefine for customization.

 -- Function: make-backup-file-name filename
     This function returns a string that is the name to use for a
     non-numbered backup file for file FILENAME.  On Unix, this is just
     FILENAME with a tilde appended.

     The standard definition of this function, on most operating
     systems, is as follows:

          (defun make-backup-file-name (file)
            "Create the non-numeric backup file name for FILE..."
            (concat file "~"))

     You can change the backup-file naming convention by redefining this
     function.  The following example redefines `make-backup-file-name'
     to prepend a `.' in addition to appending a tilde:

          (defun make-backup-file-name (filename)
            (expand-file-name
              (concat "." (file-name-nondirectory filename) "~")
              (file-name-directory filename)))

          (make-backup-file-name "backups.texi")
               => ".backups.texi~"

     Some parts of Emacs, including some Dired commands, assume that
     backup file names end with `~'.  If you do not follow that
     convention, it will not cause serious problems, but these commands
     may give less-than-desirable results.

 -- Function: find-backup-file-name filename
     This function computes the file name for a new backup file for
     FILENAME.  It may also propose certain existing backup files for
     deletion.  `find-backup-file-name' returns a list whose CAR is the
     name for the new backup file and whose CDR is a list of backup
     files whose deletion is proposed.  The value can also be `nil',
     which means not to make a backup.

     Two variables, `kept-old-versions' and `kept-new-versions',
     determine which backup versions should be kept.  This function
     keeps those versions by excluding them from the CDR of the value.
     *Note Numbered Backups::.

     In this example, the value says that `~rms/foo.~5~' is the name to
     use for the new backup file, and `~rms/foo.~3~' is an "excess"
     version that the caller should consider deleting now.

          (find-backup-file-name "~rms/foo")
               => ("~rms/foo.~5~" "~rms/foo.~3~")

 -- Function: file-newest-backup filename
     This function returns the name of the most recent backup file for
     FILENAME, or `nil' if that file has no backup files.

     Some file comparison commands use this function so that they can
     automatically compare a file with its most recent backup.


File: elisp,  Node: Auto-Saving,  Next: Reverting,  Prev: Backup Files,  Up: Backups and Auto-Saving

26.2 Auto-Saving
================

Emacs periodically saves all files that you are visiting; this is
called "auto-saving".  Auto-saving prevents you from losing more than a
limited amount of work if the system crashes.  By default, auto-saves
happen every 300 keystrokes, or after around 30 seconds of idle time.
*Note Auto Save: (emacs)Auto Save, for information on auto-save for
users.  Here we describe the functions used to implement auto-saving
and the variables that control them.

 -- Variable: buffer-auto-save-file-name
     This buffer-local variable is the name of the file used for
     auto-saving the current buffer.  It is `nil' if the buffer should
     not be auto-saved.

          buffer-auto-save-file-name
               => "/xcssun/users/rms/lewis/#backups.texi#"

 -- Command: auto-save-mode arg
     When used interactively without an argument, this command is a
     toggle switch: it turns on auto-saving of the current buffer if it
     is off, and vice versa.  When called from Lisp with no argument,
     it turns auto-saving on.  With an argument ARG, it turns
     auto-saving on if the value of ARG is `t', a nonempty list, or a
     positive integer; otherwise, it turns auto-saving off.

 -- Function: auto-save-file-name-p filename
     This function returns a non-`nil' value if FILENAME is a string
     that could be the name of an auto-save file.  It assumes the usual
     naming convention for auto-save files: a name that begins and ends
     with hash marks (`#') is a possible auto-save file name.  The
     argument FILENAME should not contain a directory part.

          (make-auto-save-file-name)
               => "/xcssun/users/rms/lewis/#backups.texi#"
          (auto-save-file-name-p "#backups.texi#")
               => 0
          (auto-save-file-name-p "backups.texi")
               => nil

     The standard definition of this function is as follows:

          (defun auto-save-file-name-p (filename)
            "Return non-nil if FILENAME can be yielded by..."
            (string-match "^#.*#$" filename))

     This function exists so that you can customize it if you wish to
     change the naming convention for auto-save files.  If you redefine
     it, be sure to redefine the function `make-auto-save-file-name'
     correspondingly.

 -- Function: make-auto-save-file-name
     This function returns the file name to use for auto-saving the
     current buffer.  This is just the file name with hash marks (`#')
     prepended and appended to it.  This function does not look at the
     variable `auto-save-visited-file-name' (described below); callers
     of this function should check that variable first.

          (make-auto-save-file-name)
               => "/xcssun/users/rms/lewis/#backups.texi#"

     Here is a simplified version of the standard definition of this
     function:

          (defun make-auto-save-file-name ()
            "Return file name to use for auto-saves \
          of current buffer.."
            (if buffer-file-name
                (concat
                 (file-name-directory buffer-file-name)
                 "#"
                 (file-name-nondirectory buffer-file-name)
                 "#")
              (expand-file-name
               (concat "#%" (buffer-name) "#"))))

     This exists as a separate function so that you can redefine it to
     customize the naming convention for auto-save files.  Be sure to
     change `auto-save-file-name-p' in a corresponding way.

 -- User Option: auto-save-visited-file-name
     If this variable is non-`nil', Emacs auto-saves buffers in the
     files they are visiting.  That is, the auto-save is done in the
     same file that you are editing.  Normally, this variable is `nil',
     so auto-save files have distinct names that are created by
     `make-auto-save-file-name'.

     When you change the value of this variable, the new value does not
     take effect in an existing buffer until the next time auto-save
     mode is reenabled in it.  If auto-save mode is already enabled,
     auto-saves continue to go in the same file name until
     `auto-save-mode' is called again.

 -- Function: recent-auto-save-p
     This function returns `t' if the current buffer has been
     auto-saved since the last time it was read in or saved.

 -- Function: set-buffer-auto-saved
     This function marks the current buffer as auto-saved.  The buffer
     will not be auto-saved again until the buffer text is changed
     again.  The function returns `nil'.

 -- User Option: auto-save-interval
     The value of this variable specifies how often to do auto-saving,
     in terms of number of input events.  Each time this many
     additional input events are read, Emacs does auto-saving for all
     buffers in which that is enabled.  Setting this to zero disables
     autosaving based on the number of characters typed.

 -- User Option: auto-save-timeout
     The value of this variable is the number of seconds of idle time
     that should cause auto-saving.  Each time the user pauses for this
     long, Emacs does auto-saving for all buffers in which that is
     enabled.  (If the current buffer is large, the specified timeout
     is multiplied by a factor that increases as the size increases;
     for a million-byte buffer, the factor is almost 4.)

     If the value is zero or `nil', then auto-saving is not done as a
     result of idleness, only after a certain number of input events as
     specified by `auto-save-interval'.

 -- Variable: auto-save-hook
     This normal hook is run whenever an auto-save is about to happen.

 -- User Option: auto-save-default
     If this variable is non-`nil', buffers that are visiting files
     have auto-saving enabled by default.  Otherwise, they do not.

 -- Command: do-auto-save &optional no-message current-only
     This function auto-saves all buffers that need to be auto-saved.
     It saves all buffers for which auto-saving is enabled and that
     have been changed since the previous auto-save.

     If any buffers are auto-saved, `do-auto-save' normally displays a
     message saying `Auto-saving...' in the echo area while auto-saving
     is going on.  However, if NO-MESSAGE is non-`nil', the message is
     inhibited.

     If CURRENT-ONLY is non-`nil', only the current buffer is
     auto-saved.

 -- Function: delete-auto-save-file-if-necessary &optional force
     This function deletes the current buffer's auto-save file if
     `delete-auto-save-files' is non-`nil'.  It is called every time a
     buffer is saved.

     Unless FORCE is non-`nil', this function only deletes the file if
     it was written by the current Emacs session since the last true
     save.

 -- User Option: delete-auto-save-files
     This variable is used by the function
     `delete-auto-save-file-if-necessary'.  If it is non-`nil', Emacs
     deletes auto-save files when a true save is done (in the visited
     file).  This saves disk space and unclutters your directory.

 -- Function: rename-auto-save-file
     This function adjusts the current buffer's auto-save file name if
     the visited file name has changed.  It also renames an existing
     auto-save file, if it was made in the current Emacs session.  If
     the visited file name has not changed, this function does nothing.

 -- Variable: buffer-saved-size
     The value of this buffer-local variable is the length of the
     current buffer, when it was last read in, saved, or auto-saved.
     This is used to detect a substantial decrease in size, and turn
     off auto-saving in response.

     If it is -1, that means auto-saving is temporarily shut off in
     this buffer due to a substantial decrease in size.  Explicitly
     saving the buffer stores a positive value in this variable, thus
     reenabling auto-saving.  Turning auto-save mode off or on also
     updates this variable, so that the substantial decrease in size is
     forgotten.

     If it is -2, that means this buffer should disregard changes in
     buffer size; in particular, it should not shut off auto-saving
     temporarily due to changes in buffer size.

 -- Variable: auto-save-list-file-name
     This variable (if non-`nil') specifies a file for recording the
     names of all the auto-save files.  Each time Emacs does
     auto-saving, it writes two lines into this file for each buffer
     that has auto-saving enabled.  The first line gives the name of
     the visited file (it's empty if the buffer has none), and the
     second gives the name of the auto-save file.

     When Emacs exits normally, it deletes this file; if Emacs crashes,
     you can look in the file to find all the auto-save files that
     might contain work that was otherwise lost.  The `recover-session'
     command uses this file to find them.

     The default name for this file specifies your home directory and
     starts with `.saves-'.  It also contains the Emacs process ID and
     the host name.

 -- User Option: auto-save-list-file-prefix
     After Emacs reads your init file, it initializes
     `auto-save-list-file-name' (if you have not already set it
     non-`nil') based on this prefix, adding the host name and process
     ID.  If you set this to `nil' in your init file, then Emacs does
     not initialize `auto-save-list-file-name'.


File: elisp,  Node: Reverting,  Prev: Auto-Saving,  Up: Backups and Auto-Saving

26.3 Reverting
==============

If you have made extensive changes to a file and then change your mind
about them, you can get rid of them by reading in the previous version
of the file with the `revert-buffer' command.  *Note Reverting a
Buffer: (emacs)Reverting.

 -- Command: revert-buffer &optional ignore-auto noconfirm
          preserve-modes
     This command replaces the buffer text with the text of the visited
     file on disk.  This action undoes all changes since the file was
     visited or saved.

     By default, if the latest auto-save file is more recent than the
     visited file, and the argument IGNORE-AUTO is `nil',
     `revert-buffer' asks the user whether to use that auto-save
     instead.  When you invoke this command interactively, IGNORE-AUTO
     is `t' if there is no numeric prefix argument; thus, the
     interactive default is not to check the auto-save file.

     Normally, `revert-buffer' asks for confirmation before it changes
     the buffer; but if the argument NOCONFIRM is non-`nil',
     `revert-buffer' does not ask for confirmation.

     Normally, this command reinitializes the buffer's major and minor
     modes using `normal-mode'.  But if PRESERVE-MODES is non-`nil',
     the modes remain unchanged.

     Reverting tries to preserve marker positions in the buffer by
     using the replacement feature of `insert-file-contents'.  If the
     buffer contents and the file contents are identical before the
     revert operation, reverting preserves all the markers.  If they
     are not identical, reverting does change the buffer; in that case,
     it preserves the markers in the unchanged text (if any) at the
     beginning and end of the buffer.  Preserving any additional
     markers would be problematical.

 -- Variable: revert-buffer-in-progress-p
     `revert-buffer' binds this variable to a non-`nil' value while it
     is working.

   You can customize how `revert-buffer' does its work by setting the
variables described in the rest of this section.

 -- User Option: revert-without-query
     This variable holds a list of files that should be reverted without
     query.  The value is a list of regular expressions.  If the
     visited file name matches one of these regular expressions, and
     the file has changed on disk but the buffer is not modified, then
     `revert-buffer' reverts the file without asking the user for
     confirmation.

   Some major modes customize `revert-buffer' by making buffer-local
bindings for these variables:

 -- Variable: revert-buffer-function
     The value of this variable is the function to use to revert this
     buffer.  If non-`nil', it should be a function with two optional
     arguments to do the work of reverting.  The two optional arguments,
     IGNORE-AUTO and NOCONFIRM, are the arguments that `revert-buffer'
     received.  If the value is `nil', reverting works the usual way.

     Modes such as Dired mode, in which the text being edited does not
     consist of a file's contents but can be regenerated in some other
     fashion, can give this variable a buffer-local value that is a
     function to regenerate the contents.

 -- Variable: revert-buffer-insert-file-contents-function
     The value of this variable, if non-`nil', specifies the function
     to use to insert the updated contents when reverting this buffer.
     The function receives two arguments: first the file name to use;
     second, `t' if the user has asked to read the auto-save file.

     The reason for a mode to set this variable instead of
     `revert-buffer-function' is to avoid duplicating or replacing the
     rest of what `revert-buffer' does: asking for confirmation,
     clearing the undo list, deciding the proper major mode, and
     running the hooks listed below.

 -- Variable: before-revert-hook
     This normal hook is run by `revert-buffer' before inserting the
     modified contents--but only if `revert-buffer-function' is `nil'.

 -- Variable: after-revert-hook
     This normal hook is run by `revert-buffer' after inserting the
     modified contents--but only if `revert-buffer-function' is `nil'.

 -- Variable: buffer-stale-function
     The value of this variable, if non-`nil', specifies a function to
     call to check whether a non-file buffer needs reverting (*note
     Supporting additional buffers: (emacs)Supporting additional
     buffers.).


File: elisp,  Node: Buffers,  Next: Windows,  Prev: Backups and Auto-Saving,  Up: Top

27 Buffers
**********

A "buffer" is a Lisp object containing text to be edited.  Buffers are
used to hold the contents of files that are being visited; there may
also be buffers that are not visiting files.  While several buffers may
exist at one time, only one buffer is designated the "current buffer"
at any time.  Most editing commands act on the contents of the current
buffer.  Each buffer, including the current buffer, may or may not be
displayed in any windows.

* Menu:

* Buffer Basics::       What is a buffer?
* Current Buffer::      Designating a buffer as current
                          so that primitives will access its contents.
* Buffer Names::        Accessing and changing buffer names.
* Buffer File Name::    The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is "modified" if it needs to be saved.
* Modification Time::   Determining whether the visited file was changed
                         "behind Emacs's back".
* Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
* The Buffer List::     How to look at all the existing buffers.
* Creating Buffers::    Functions that create buffers.
* Killing Buffers::     Buffers exist until explicitly killed.
* Indirect Buffers::    An indirect buffer shares text with some other buffer.
* Swapping Text::       Swapping text between two buffers.
* Buffer Gap::          The gap in the buffer.


File: elisp,  Node: Buffer Basics,  Next: Current Buffer,  Up: Buffers

27.1 Buffer Basics
==================

A "buffer" is a Lisp object containing text to be edited.  Buffers are
used to hold the contents of files that are being visited; there may
also be buffers that are not visiting files.  Although several buffers
normally exist, only one buffer is designated the "current buffer" at
any time.  Most editing commands act on the contents of the current
buffer.  Each buffer, including the current buffer, may or may not be
displayed in any windows.

Buffers in Emacs editing are objects that have distinct names and hold
text that can be edited.  Buffers appear to Lisp programs as a special
data type.  You can think of the contents of a buffer as a string that
you can extend; insertions and deletions may occur in any part of the
buffer.  *Note Text::.

   A Lisp buffer object contains numerous pieces of information.  Some
of this information is directly accessible to the programmer through
variables, while other information is accessible only through
special-purpose functions.  For example, the visited file name is
directly accessible through a variable, while the value of point is
accessible only through a primitive function.

   Buffer-specific information that is directly accessible is stored in
"buffer-local" variable bindings, which are variable values that are
effective only in a particular buffer.  This feature allows each buffer
to override the values of certain variables.  Most major modes override
variables such as `fill-column' or `comment-column' in this way.  For
more information about buffer-local variables and functions related to
them, see *note Buffer-Local Variables::.

   For functions and variables related to visiting files in buffers, see
*note Visiting Files:: and *note Saving Buffers::.  For functions and
variables related to the display of buffers in windows, see *note
Buffers and Windows::.

 -- Function: bufferp object
     This function returns `t' if OBJECT is a buffer, `nil' otherwise.


File: elisp,  Node: Current Buffer,  Next: Buffer Names,  Prev: Buffer Basics,  Up: Buffers

27.2 The Current Buffer
=======================

There are, in general, many buffers in an Emacs session.  At any time,
one of them is designated the "current buffer"--the buffer in which
most editing takes place.  Most of the primitives for examining or
changing text operate implicitly on the current buffer (*note Text::).

   Normally, the buffer displayed in the selected window is the current
buffer, but this is not always so: a Lisp program can temporarily
designate any buffer as current in order to operate on its contents,
without changing what is displayed on the screen.  The most basic
function for designating a current buffer is `set-buffer'.

 -- Function: current-buffer
     This function returns the current buffer.

          (current-buffer)
               => #<buffer buffers.texi>

 -- Function: set-buffer buffer-or-name
     This function makes BUFFER-OR-NAME the current buffer.
     BUFFER-OR-NAME must be an existing buffer or the name of an
     existing buffer.  The return value is the buffer made current.

     This function does not display the buffer in any window, so the
     user cannot necessarily see the buffer.  But Lisp programs will
     now operate on it.

   When an editing command returns to the editor command loop, Emacs
automatically calls `set-buffer' on the buffer shown in the selected
window.  This is to prevent confusion: it ensures that the buffer that
the cursor is in, when Emacs reads a command, is the buffer to which
that command applies (*note Command Loop::).  Thus, you should not use
`set-buffer' to switch visibly to a different buffer; for that, use the
functions described in *note Switching Buffers::.

   When writing a Lisp function, do _not_ rely on this behavior of the
command loop to restore the current buffer after an operation.  Editing
commands can also be called as Lisp functions by other programs, not
just from the command loop; it is convenient for the caller if the
subroutine does not change which buffer is current (unless, of course,
that is the subroutine's purpose).

   To operate temporarily on another buffer, put the `set-buffer'
within a `save-current-buffer' form.  Here, as an example, is a
simplified version of the command `append-to-buffer':

     (defun append-to-buffer (buffer start end)
       "Append the text of the region to BUFFER."
       (interactive "BAppend to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (save-current-buffer
           (set-buffer (get-buffer-create buffer))
           (insert-buffer-substring oldbuf start end))))

Here, we bind a local variable to record the current buffer, and then
`save-current-buffer' arranges to make it current again later.  Next,
`set-buffer' makes the specified buffer current, and
`insert-buffer-substring' copies the string from the original buffer to
the specified (and now current) buffer.

   Alternatively, we can use the `with-current-buffer' macro:

     (defun append-to-buffer (buffer start end)
       "Append the text of the region to BUFFER."
       (interactive "BAppend to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (with-current-buffer (get-buffer-create buffer)
           (insert-buffer-substring oldbuf start end))))

   In either case, if the buffer appended to happens to be displayed in
some window, the next redisplay will show how its text has changed.  If
it is not displayed in any window, you will not see the change
immediately on the screen.  The command causes the buffer to become
current temporarily, but does not cause it to be displayed.

   If you make local bindings (with `let' or function arguments) for a
variable that may also have buffer-local bindings, make sure that the
same buffer is current at the beginning and at the end of the local
binding's scope.  Otherwise you might bind it in one buffer and unbind
it in another!

   Do not rely on using `set-buffer' to change the current buffer back,
because that won't do the job if a quit happens while the wrong buffer
is current.  For instance, in the previous example, it would have been
wrong to do this:

       (let ((oldbuf (current-buffer)))
         (set-buffer (get-buffer-create buffer))
         (insert-buffer-substring oldbuf start end)
         (set-buffer oldbuf))

Using `save-current-buffer' or `with-current-buffer', as we did,
correctly handles quitting, errors, and `throw', as well as ordinary
evaluation.

 -- Special Form: save-current-buffer body...
     The `save-current-buffer' special form saves the identity of the
     current buffer, evaluates the BODY forms, and finally restores
     that buffer as current.  The return value is the value of the last
     form in BODY.  The current buffer is restored even in case of an
     abnormal exit via `throw' or error (*note Nonlocal Exits::).

     If the buffer that used to be current has been killed by the time
     of exit from `save-current-buffer', then it is not made current
     again, of course.  Instead, whichever buffer was current just
     before exit remains current.

 -- Macro: with-current-buffer buffer-or-name body...
     The `with-current-buffer' macro saves the identity of the current
     buffer, makes BUFFER-OR-NAME current, evaluates the BODY forms,
     and finally restores the current buffer.  BUFFER-OR-NAME must
     specify an existing buffer or the name of an existing buffer.

     The return value is the value of the last form in BODY.  The
     current buffer is restored even in case of an abnormal exit via
     `throw' or error (*note Nonlocal Exits::).

 -- Macro: with-temp-buffer body...
     The `with-temp-buffer' macro evaluates the BODY forms with a
     temporary buffer as the current buffer.  It saves the identity of
     the current buffer, creates a temporary buffer and makes it
     current, evaluates the BODY forms, and finally restores the
     previous current buffer while killing the temporary buffer.  By
     default, undo information (*note Undo::) is not recorded in the
     buffer created by this macro (but BODY can enable that, if needed).

     The return value is the value of the last form in BODY.  You can
     return the contents of the temporary buffer by using
     `(buffer-string)' as the last form.

     The current buffer is restored even in case of an abnormal exit via
     `throw' or error (*note Nonlocal Exits::).

     See also `with-temp-file' in *note Writing to Files: Definition of
     with-temp-file.


File: elisp,  Node: Buffer Names,  Next: Buffer File Name,  Prev: Current Buffer,  Up: Buffers

27.3 Buffer Names
=================

Each buffer has a unique name, which is a string.  Many of the
functions that work on buffers accept either a buffer or a buffer name
as an argument.  Any argument called BUFFER-OR-NAME is of this sort,
and an error is signaled if it is neither a string nor a buffer.  Any
argument called BUFFER must be an actual buffer object, not a name.

   Buffers that are ephemeral and generally uninteresting to the user
have names starting with a space, so that the `list-buffers' and
`buffer-menu' commands don't mention them (but if such a buffer visits
a file, it *is* mentioned).  A name starting with space also initially
disables recording undo information; see *note Undo::.

 -- Function: buffer-name &optional buffer
     This function returns the name of BUFFER as a string.  BUFFER
     defaults to the current buffer.

     If `buffer-name' returns `nil', it means that BUFFER has been
     killed.  *Note Killing Buffers::.

          (buffer-name)
               => "buffers.texi"

          (setq foo (get-buffer "temp"))
               => #<buffer temp>
          (kill-buffer foo)
               => nil
          (buffer-name foo)
               => nil
          foo
               => #<killed buffer>

 -- Command: rename-buffer newname &optional unique
     This function renames the current buffer to NEWNAME.  An error is
     signaled if NEWNAME is not a string.

     Ordinarily, `rename-buffer' signals an error if NEWNAME is already
     in use.  However, if UNIQUE is non-`nil', it modifies NEWNAME to
     make a name that is not in use.  Interactively, you can make
     UNIQUE non-`nil' with a numeric prefix argument.  (This is how the
     command `rename-uniquely' is implemented.)

     This function returns the name actually given to the buffer.

 -- Function: get-buffer buffer-or-name
     This function returns the buffer specified by BUFFER-OR-NAME.  If
     BUFFER-OR-NAME is a string and there is no buffer with that name,
     the value is `nil'.  If BUFFER-OR-NAME is a buffer, it is returned
     as given; that is not very useful, so the argument is usually a
     name.  For example:

          (setq b (get-buffer "lewis"))
               => #<buffer lewis>
          (get-buffer b)
               => #<buffer lewis>
          (get-buffer "Frazzle-nots")
               => nil

     See also the function `get-buffer-create' in *note Creating
     Buffers::.

 -- Function: generate-new-buffer-name starting-name &optional ignore
     This function returns a name that would be unique for a new
     buffer--but does not create the buffer.  It starts with
     STARTING-NAME, and produces a name not currently in use for any
     buffer by appending a number inside of `<...>'.  It starts at 2
     and keeps incrementing the number until it is not the name of an
     existing buffer.

     If the optional second argument IGNORE is non-`nil', it should be
     a string, a potential buffer name.  It means to consider that
     potential buffer acceptable, if it is tried, even it is the name
     of an existing buffer (which would normally be rejected).  Thus, if
     buffers named `foo', `foo<2>', `foo<3>' and `foo<4>' exist,

          (generate-new-buffer-name "foo")
               => "foo<5>"
          (generate-new-buffer-name "foo" "foo<3>")
               => "foo<3>"
          (generate-new-buffer-name "foo" "foo<6>")
               => "foo<5>"

     See the related function `generate-new-buffer' in *note Creating
     Buffers::.


File: elisp,  Node: Buffer File Name,  Next: Buffer Modification,  Prev: Buffer Names,  Up: Buffers

27.4 Buffer File Name
=====================

The "buffer file name" is the name of the file that is visited in that
buffer.  When a buffer is not visiting a file, its buffer file name is
`nil'.  Most of the time, the buffer name is the same as the
nondirectory part of the buffer file name, but the buffer file name and
the buffer name are distinct and can be set independently.  *Note
Visiting Files::.

 -- Function: buffer-file-name &optional buffer
     This function returns the absolute file name of the file that
     BUFFER is visiting.  If BUFFER is not visiting any file,
     `buffer-file-name' returns `nil'.  If BUFFER is not supplied, it
     defaults to the current buffer.

          (buffer-file-name (other-buffer))
               => "/usr/user/lewis/manual/files.texi"

 -- Variable: buffer-file-name
     This buffer-local variable contains the name of the file being
     visited in the current buffer, or `nil' if it is not visiting a
     file.  It is a permanent local variable, unaffected by
     `kill-all-local-variables'.

          buffer-file-name
               => "/usr/user/lewis/manual/buffers.texi"

     It is risky to change this variable's value without doing various
     other things.  Normally it is better to use
     `set-visited-file-name' (see below); some of the things done
     there, such as changing the buffer name, are not strictly
     necessary, but others are essential to avoid confusing Emacs.

 -- Variable: buffer-file-truename
     This buffer-local variable holds the abbreviated truename of the
     file visited in the current buffer, or `nil' if no file is visited.
     It is a permanent local, unaffected by `kill-all-local-variables'.
     *Note Truenames::, and *note abbreviate-file-name::.

 -- Variable: buffer-file-number
     This buffer-local variable holds the file number and directory
     device number of the file visited in the current buffer, or `nil'
     if no file or a nonexistent file is visited.  It is a permanent
     local, unaffected by `kill-all-local-variables'.

     The value is normally a list of the form `(FILENUM DEVNUM)'.  This
     pair of numbers uniquely identifies the file among all files
     accessible on the system.  See the function `file-attributes', in
     *note File Attributes::, for more information about them.

     If `buffer-file-name' is the name of a symbolic link, then both
     numbers refer to the recursive target.

 -- Function: get-file-buffer filename
     This function returns the buffer visiting file FILENAME.  If there
     is no such buffer, it returns `nil'.  The argument FILENAME, which
     must be a string, is expanded (*note File Name Expansion::), then
     compared against the visited file names of all live buffers.  Note
     that the buffer's `buffer-file-name' must match the expansion of
     FILENAME exactly.  This function will not recognize other names
     for the same file.

          (get-file-buffer "buffers.texi")
              => #<buffer buffers.texi>

     In unusual circumstances, there can be more than one buffer
     visiting the same file name.  In such cases, this function returns
     the first such buffer in the buffer list.

 -- Function: find-buffer-visiting filename &optional predicate
     This is like `get-file-buffer', except that it can return any
     buffer visiting the file _possibly under a different name_.  That
     is, the buffer's `buffer-file-name' does not need to match the
     expansion of FILENAME exactly, it only needs to refer to the same
     file.  If PREDICATE is non-`nil', it should be a function of one
     argument, a buffer visiting FILENAME.  The buffer is only
     considered a suitable return value if PREDICATE returns non-`nil'.
     If it can not find a suitable buffer to return,
     `find-buffer-visiting' returns `nil'.

 -- Command: set-visited-file-name filename &optional no-query
          along-with-file
     If FILENAME is a non-empty string, this function changes the name
     of the file visited in the current buffer to FILENAME.  (If the
     buffer had no visited file, this gives it one.)  The _next time_
     the buffer is saved it will go in the newly-specified file.

     This command marks the buffer as modified, since it does not (as
     far as Emacs knows) match the contents of FILENAME, even if it
     matched the former visited file.  It also renames the buffer to
     correspond to the new file name, unless the new name is already in
     use.

     If FILENAME is `nil' or the empty string, that stands for "no
     visited file".  In this case, `set-visited-file-name' marks the
     buffer as having no visited file, without changing the buffer's
     modified flag.

     Normally, this function asks the user for confirmation if there
     already is a buffer visiting FILENAME.  If NO-QUERY is non-`nil',
     that prevents asking this question.  If there already is a buffer
     visiting FILENAME, and the user confirms or QUERY is non-`nil',
     this function makes the new buffer name unique by appending a
     number inside of `<...>' to FILENAME.

     If ALONG-WITH-FILE is non-`nil', that means to assume that the
     former visited file has been renamed to FILENAME.  In this case,
     the command does not change the buffer's modified flag, nor the
     buffer's recorded last file modification time as reported by
     `visited-file-modtime' (*note Modification Time::).  If
     ALONG-WITH-FILE is `nil', this function clears the recorded last
     file modification time, after which `visited-file-modtime' returns
     zero.

     When the function `set-visited-file-name' is called interactively,
     it prompts for FILENAME in the minibuffer.

 -- Variable: list-buffers-directory
     This buffer-local variable specifies a string to display in a
     buffer listing where the visited file name would go, for buffers
     that don't have a visited file name.  Dired buffers use this
     variable.


File: elisp,  Node: Buffer Modification,  Next: Modification Time,  Prev: Buffer File Name,  Up: Buffers

27.5 Buffer Modification
========================

Emacs keeps a flag called the "modified flag" for each buffer, to
record whether you have changed the text of the buffer.  This flag is
set to `t' whenever you alter the contents of the buffer, and cleared
to `nil' when you save it.  Thus, the flag shows whether there are
unsaved changes.  The flag value is normally shown in the mode line
(*note Mode Line Variables::), and controls saving (*note Saving
Buffers::) and auto-saving (*note Auto-Saving::).

   Some Lisp programs set the flag explicitly.  For example, the
function `set-visited-file-name' sets the flag to `t', because the text
does not match the newly-visited file, even if it is unchanged from the
file formerly visited.

   The functions that modify the contents of buffers are described in
*note Text::.

 -- Function: buffer-modified-p &optional buffer
     This function returns `t' if the buffer BUFFER has been modified
     since it was last read in from a file or saved, or `nil'
     otherwise.  If BUFFER is not supplied, the current buffer is
     tested.

 -- Function: set-buffer-modified-p flag
     This function marks the current buffer as modified if FLAG is
     non-`nil', or as unmodified if the flag is `nil'.

     Another effect of calling this function is to cause unconditional
     redisplay of the mode line for the current buffer.  In fact, the
     function `force-mode-line-update' works by doing this:

          (set-buffer-modified-p (buffer-modified-p))

 -- Function: restore-buffer-modified-p flag
     Like `set-buffer-modified-p', but does not force redisplay of mode
     lines.

 -- Command: not-modified &optional arg
     This command marks the current buffer as unmodified, and not
     needing to be saved.  If ARG is non-`nil', it marks the buffer as
     modified, so that it will be saved at the next suitable occasion.
     Interactively, ARG is the prefix argument.

     Don't use this function in programs, since it prints a message in
     the echo area; use `set-buffer-modified-p' (above) instead.

 -- Function: buffer-modified-tick &optional buffer
     This function returns BUFFER's modification-count.  This is a
     counter that increments every time the buffer is modified.  If
     BUFFER is `nil' (or omitted), the current buffer is used.  The
     counter can wrap around occasionally.

 -- Function: buffer-chars-modified-tick &optional buffer
     This function returns BUFFER's character-change modification-count.
     Changes to text properties leave this counter unchanged; however,
     each time text is inserted or removed from the buffer, the counter
     is reset to the value that would be returned by
     `buffer-modified-tick'.  By comparing the values returned by two
     `buffer-chars-modified-tick' calls, you can tell whether a
     character change occurred in that buffer in between the calls.  If
     BUFFER is `nil' (or omitted), the current buffer is used.


File: elisp,  Node: Modification Time,  Next: Read Only Buffers,  Prev: Buffer Modification,  Up: Buffers

27.6 Buffer Modification Time
=============================

Suppose that you visit a file and make changes in its buffer, and
meanwhile the file itself is changed on disk.  At this point, saving the
buffer would overwrite the changes in the file.  Occasionally this may
be what you want, but usually it would lose valuable information.  Emacs
therefore checks the file's modification time using the functions
described below before saving the file.  (*Note File Attributes::, for
how to examine a file's modification time.)

 -- Function: verify-visited-file-modtime &optional buffer
     This function compares what BUFFER (by default, the
     current-buffer) has recorded for the modification time of its
     visited file against the actual modification time of the file as
     recorded by the operating system.  The two should be the same
     unless some other process has written the file since Emacs visited
     or saved it.

     The function returns `t' if the last actual modification time and
     Emacs's recorded modification time are the same, `nil' otherwise.
     It also returns `t' if the buffer has no recorded last
     modification time, that is if `visited-file-modtime' would return
     zero.

     It always returns `t' for buffers that are not visiting a file,
     even if `visited-file-modtime' returns a non-zero value.  For
     instance, it always returns `t' for dired buffers.  It returns `t'
     for buffers that are visiting a file that does not exist and never
     existed, but `nil' for file-visiting buffers whose file has been
     deleted.

 -- Function: clear-visited-file-modtime
     This function clears out the record of the last modification time
     of the file being visited by the current buffer.  As a result, the
     next attempt to save this buffer will not complain of a
     discrepancy in file modification times.

     This function is called in `set-visited-file-name' and other
     exceptional places where the usual test to avoid overwriting a
     changed file should not be done.

 -- Function: visited-file-modtime
     This function returns the current buffer's recorded last file
     modification time, as a list of the form `(HIGH LOW)'.  (This is
     the same format that `file-attributes' uses to return time values;
     see *note File Attributes::.)

     If the buffer has no recorded last modification time, this function
     returns zero.  This case occurs, for instance, if the buffer is not
     visiting a file or if the time has been explicitly cleared by
     `clear-visited-file-modtime'.  Note, however, that
     `visited-file-modtime' returns a list for some non-file buffers
     too.  For instance, in a Dired buffer listing a directory, it
     returns the last modification time of that directory, as recorded
     by Dired.

     For a new buffer visiting a not yet existing file, HIGH is -1 and
     LOW is 65535, that is, 2**16 - 1.

 -- Function: set-visited-file-modtime &optional time
     This function updates the buffer's record of the last modification
     time of the visited file, to the value specified by TIME if TIME
     is not `nil', and otherwise to the last modification time of the
     visited file.

     If TIME is neither `nil' nor zero, it should have the form `(HIGH
     . LOW)' or `(HIGH LOW)', in either case containing two integers,
     each of which holds 16 bits of the time.

     This function is useful if the buffer was not read from the file
     normally, or if the file itself has been changed for some known
     benign reason.

 -- Function: ask-user-about-supersession-threat filename
     This function is used to ask a user how to proceed after an
     attempt to modify an buffer visiting file FILENAME when the file
     is newer than the buffer text.  Emacs detects this because the
     modification time of the file on disk is newer than the last
     save-time of the buffer.  This means some other program has
     probably altered the file.

     Depending on the user's answer, the function may return normally,
     in which case the modification of the buffer proceeds, or it may
     signal a `file-supersession' error with data `(FILENAME)', in which
     case the proposed buffer modification is not allowed.

     This function is called automatically by Emacs on the proper
     occasions.  It exists so you can customize Emacs by redefining it.
     See the file `userlock.el' for the standard definition.

     See also the file locking mechanism in *note File Locks::.


File: elisp,  Node: Read Only Buffers,  Next: The Buffer List,  Prev: Modification Time,  Up: Buffers

27.7 Read-Only Buffers
======================

If a buffer is "read-only", then you cannot change its contents,
although you may change your view of the contents by scrolling and
narrowing.

   Read-only buffers are used in two kinds of situations:

   * A buffer visiting a write-protected file is normally read-only.

     Here, the purpose is to inform the user that editing the buffer
     with the aim of saving it in the file may be futile or
     undesirable.  The user who wants to change the buffer text despite
     this can do so after clearing the read-only flag with `C-x C-q'.

   * Modes such as Dired and Rmail make buffers read-only when altering
     the contents with the usual editing commands would probably be a
     mistake.

     The special commands of these modes bind `buffer-read-only' to
     `nil' (with `let') or bind `inhibit-read-only' to `t' around the
     places where they themselves change the text.

 -- Variable: buffer-read-only
     This buffer-local variable specifies whether the buffer is
     read-only.  The buffer is read-only if this variable is non-`nil'.

 -- Variable: inhibit-read-only
     If this variable is non-`nil', then read-only buffers and,
     depending on the actual value, some or all read-only characters
     may be modified.  Read-only characters in a buffer are those that
     have non-`nil' `read-only' properties (either text properties or
     overlay properties).  *Note Special Properties::, for more
     information about text properties.  *Note Overlays::, for more
     information about overlays and their properties.

     If `inhibit-read-only' is `t', all `read-only' character
     properties have no effect.  If `inhibit-read-only' is a list, then
     `read-only' character properties have no effect if they are members
     of the list (comparison is done with `eq').

 -- Command: toggle-read-only &optional arg
     This command toggles whether the current buffer is read-only.  It
     is intended for interactive use; do not use it in programs (it may
     have side-effects, such as enabling View mode, and does not affect
     read-only text properties).  To change the read-only state of a
     buffer in a program, explicitly set `buffer-read-only' to the
     proper value.  To temporarily ignore a read-only state, bind
     `inhibit-read-only'.

     If ARG is non-`nil', it should be a raw prefix argument.
     `toggle-read-only' sets `buffer-read-only' to `t' if the numeric
     value of that prefix argument is positive and to `nil' otherwise.
     *Note Prefix Command Arguments::.

 -- Function: barf-if-buffer-read-only
     This function signals a `buffer-read-only' error if the current
     buffer is read-only.  *Note Using Interactive::, for another way to
     signal an error if the current buffer is read-only.


File: elisp,  Node: The Buffer List,  Next: Creating Buffers,  Prev: Read Only Buffers,  Up: Buffers

27.8 The Buffer List
====================

The "buffer list" is a list of all live buffers.  The order of the
buffers in this list is based primarily on how recently each buffer has
been displayed in a window.  Several functions, notably `other-buffer',
use this ordering.  A buffer list displayed for the user also follows
this order.

   Creating a buffer adds it to the end of the buffer list, and killing
a buffer removes it from that list.  A buffer moves to the front of
this list whenever it is chosen for display in a window (*note
Switching Buffers::) or a window displaying it is selected (*note
Selecting Windows::).  A buffer moves to the end of the list when it is
buried (see `bury-buffer', below).  There are no functions available to
the Lisp programmer which directly manipulate the buffer list.

   In addition to the fundamental buffer list just described, Emacs
maintains a local buffer list for each frame, in which the buffers that
have been displayed (or had their windows selected) in that frame come
first.  (This order is recorded in the frame's `buffer-list' frame
parameter; see *note Buffer Parameters::.)  Buffers never displayed in
that frame come afterward, ordered according to the fundamental buffer
list.

 -- Function: buffer-list &optional frame
     This function returns the buffer list, including all buffers, even
     those whose names begin with a space.  The elements are actual
     buffers, not their names.

     If FRAME is a frame, this returns FRAME's local buffer list.  If
     FRAME is `nil' or omitted, the fundamental buffer list is used:
     the buffers appear in order of most recent display or selection,
     regardless of which frames they were displayed on.

          (buffer-list)
               => (#<buffer buffers.texi>
                   #<buffer  *Minibuf-1*> #<buffer buffer.c>
                   #<buffer *Help*> #<buffer TAGS>)

          ;; Note that the name of the minibuffer
          ;;   begins with a space!
          (mapcar (function buffer-name) (buffer-list))
              => ("buffers.texi" " *Minibuf-1*"
                  "buffer.c" "*Help*" "TAGS")

   The list returned by `buffer-list' is constructed specifically; it
is not an internal Emacs data structure, and modifying it has no effect
on the order of buffers.  If you want to change the order of buffers in
the fundamental buffer list, here is an easy way:

     (defun reorder-buffer-list (new-list)
       (while new-list
         (bury-buffer (car new-list))
         (setq new-list (cdr new-list))))

   With this method, you can specify any order for the list, but there
is no danger of losing a buffer or adding something that is not a valid
live buffer.

   To change the order or value of a specific frame's buffer list, set
that frame's `buffer-list' parameter with `modify-frame-parameters'
(*note Parameter Access::).

 -- Function: other-buffer &optional buffer visible-ok frame
     This function returns the first buffer in the buffer list other
     than BUFFER.  Usually, this is the buffer appearing in the most
     recently selected window (in frame FRAME or else the selected
     frame, *note Input Focus::), aside from BUFFER.  Buffers whose
     names start with a space are not considered at all.

     If BUFFER is not supplied (or if it is not a live buffer), then
     `other-buffer' returns the first buffer in the selected frame's
     local buffer list. (If FRAME is non-`nil', it returns the first
     buffer in FRAME's local buffer list instead.)

     If FRAME has a non-`nil' `buffer-predicate' parameter, then
     `other-buffer' uses that predicate to decide which buffers to
     consider.  It calls the predicate once for each buffer, and if the
     value is `nil', that buffer is ignored.  *Note Buffer Parameters::.

     If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
     visible in any window on any visible frame, except as a last
     resort.  If VISIBLE-OK is non-`nil', then it does not matter
     whether a buffer is displayed somewhere or not.

     If no suitable buffer exists, the buffer `*scratch*' is returned
     (and created, if necessary).

 -- Function: last-buffer &optional buffer visible-ok frame
     This function returns the last buffer in FRAME's buffer list other
     than BUFFER.  If FRAME is omitted or `nil', it uses the selected
     frame's buffer list.

     The argument VISIBLE-OK is handled as with `other-buffer', see
     above.  If no suitable buffer can be found, the buffer `*scratch*'
     is returned.

 -- Command: bury-buffer &optional buffer-or-name
     This command puts BUFFER-OR-NAME at the end of the buffer list,
     without changing the order of any of the other buffers on the list.
     This buffer therefore becomes the least desirable candidate for
     `other-buffer' to return.  The argument can be either a buffer
     itself or the name of one.

     This functions operates on each frame's `buffer-list' parameter as
     well as the fundamental buffer list; therefore, the buffer that
     you bury will come last in the value of `(buffer-list FRAME)' and
     in the value of `(buffer-list)'.  In addition, it also puts the
     buffer at the end of the list of buffer of the selected window
     (*note Window History::) provided it is shown in that window.

     If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
     current buffer.  In addition, if the current buffer is displayed
     in the selected window, this makes sure that the window is either
     deleted or another buffer is shown in it.  More precisely, if the
     window is dedicated (*note Dedicated Windows::) and there are
     other windows on its frame, the window is deleted.  If the window
     is both dedicated and the only window on its frame's terminal, the
     function specified by `frame-auto-hide-function' (*note Quitting
     Windows::) will deal with the window.  If the window is not
     dedicated to its buffer, it calls `switch-to-prev-buffer' (*note
     Window History::) to show another buffer in that window.  If
     BUFFER-OR-NAME is displayed in some other window, it remains
     displayed there.

     To replace a buffer in all the windows that display it, use
     `replace-buffer-in-windows', *Note Buffers and Windows::.

 -- Command: unbury-buffer
     This command switches to the last buffer in the local buffer list
     of the selected frame.  More precisely, it calls the function
     `switch-to-buffer' (*note Switching Buffers::), to display the
     buffer returned by `last-buffer' (see above), in the selected
     window.


File: elisp,  Node: Creating Buffers,  Next: Killing Buffers,  Prev: The Buffer List,  Up: Buffers

27.9 Creating Buffers
=====================

This section describes the two primitives for creating buffers.
`get-buffer-create' creates a buffer if it finds no existing buffer
with the specified name; `generate-new-buffer' always creates a new
buffer and gives it a unique name.

   Other functions you can use to create buffers include
`with-output-to-temp-buffer' (*note Temporary Displays::) and
`create-file-buffer' (*note Visiting Files::).  Starting a subprocess
can also create a buffer (*note Processes::).

 -- Function: get-buffer-create buffer-or-name
     This function returns a buffer named BUFFER-OR-NAME.  The buffer
     returned does not become the current buffer--this function does not
     change which buffer is current.

     BUFFER-OR-NAME must be either a string or an existing buffer.  If
     it is a string and a live buffer with that name already exists,
     `get-buffer-create' returns that buffer.  If no such buffer exists,
     it creates a new buffer.  If BUFFER-OR-NAME is a buffer instead of
     a string, it is returned as given, even if it is dead.

          (get-buffer-create "foo")
               => #<buffer foo>

     The major mode for a newly created buffer is set to Fundamental
     mode.  (The default value of the variable `major-mode' is handled
     at a higher level; see *note Auto Major Mode::.)  If the name
     begins with a space, the buffer initially disables undo
     information recording (*note Undo::).

 -- Function: generate-new-buffer name
     This function returns a newly created, empty buffer, but does not
     make it current.  The name of the buffer is generated by passing
     NAME to the function `generate-new-buffer-name' (*note Buffer
     Names::).  Thus, if there is no buffer named NAME, then that is
     the name of the new buffer; if that name is in use, a suffix of the
     form `<N>', where N is an integer, is appended to NAME.

     An error is signaled if NAME is not a string.

          (generate-new-buffer "bar")
               => #<buffer bar>
          (generate-new-buffer "bar")
               => #<buffer bar<2>>
          (generate-new-buffer "bar")
               => #<buffer bar<3>>

     The major mode for the new buffer is set to Fundamental mode.  The
     default value of the variable `major-mode' is handled at a higher
     level.  *Note Auto Major Mode::.


File: elisp,  Node: Killing Buffers,  Next: Indirect Buffers,  Prev: Creating Buffers,  Up: Buffers

27.10 Killing Buffers
=====================

"Killing a buffer" makes its name unknown to Emacs and makes the memory
space it occupied available for other use.

   The buffer object for the buffer that has been killed remains in
existence as long as anything refers to it, but it is specially marked
so that you cannot make it current or display it.  Killed buffers retain
their identity, however; if you kill two distinct buffers, they remain
distinct according to `eq' although both are dead.

   If you kill a buffer that is current or displayed in a window, Emacs
automatically selects or displays some other buffer instead.  This
means that killing a buffer can change the current buffer.  Therefore,
when you kill a buffer, you should also take the precautions associated
with changing the current buffer (unless you happen to know that the
buffer being killed isn't current).  *Note Current Buffer::.

   If you kill a buffer that is the base buffer of one or more indirect
buffers (*note Indirect Buffers::), the indirect buffers are
automatically killed as well.

   The `buffer-name' of a buffer is `nil' if, and only if, the buffer
is killed.  A buffer that has not been killed is called a "live"
buffer.  To test whether a buffer is live or killed, use the function
`buffer-live-p' (see below).

 -- Command: kill-buffer &optional buffer-or-name
     This function kills the buffer BUFFER-OR-NAME, freeing all its
     memory for other uses or to be returned to the operating system.
     If BUFFER-OR-NAME is `nil' or omitted, it kills the current buffer.

     Any processes that have this buffer as the `process-buffer' are
     sent the `SIGHUP' ("hangup") signal, which normally causes them to
     terminate.  *Note Signals to Processes::.

     If the buffer is visiting a file and contains unsaved changes,
     `kill-buffer' asks the user to confirm before the buffer is killed.
     It does this even if not called interactively.  To prevent the
     request for confirmation, clear the modified flag before calling
     `kill-buffer'.  *Note Buffer Modification::.

     This function calls `replace-buffer-in-windows' for cleaning up
     all windows currently displaying the buffer to be killed.

     Killing a buffer that is already dead has no effect.

     This function returns `t' if it actually killed the buffer.  It
     returns `nil' if the user refuses to confirm or if BUFFER-OR-NAME
     was already dead.

          (kill-buffer "foo.unchanged")
               => t
          (kill-buffer "foo.changed")

          ---------- Buffer: Minibuffer ----------
          Buffer foo.changed modified; kill anyway? (yes or no) yes
          ---------- Buffer: Minibuffer ----------

               => t

 -- Variable: kill-buffer-query-functions
     After confirming unsaved changes, `kill-buffer' calls the functions
     in the list `kill-buffer-query-functions', in order of appearance,
     with no arguments.  The buffer being killed is the current buffer
     when they are called.  The idea of this feature is that these
     functions will ask for confirmation from the user.  If any of them
     returns `nil', `kill-buffer' spares the buffer's life.

 -- Variable: kill-buffer-hook
     This is a normal hook run by `kill-buffer' after asking all the
     questions it is going to ask, just before actually killing the
     buffer.  The buffer to be killed is current when the hook
     functions run.  *Note Hooks::.  This variable is a permanent
     local, so its local binding is not cleared by changing major modes.

 -- User Option: buffer-offer-save
     This variable, if non-`nil' in a particular buffer, tells
     `save-buffers-kill-emacs' and `save-some-buffers' (if the second
     optional argument to that function is `t') to offer to save that
     buffer, just as they offer to save file-visiting buffers.  *Note
     Definition of save-some-buffers::.  The variable
     `buffer-offer-save' automatically becomes buffer-local when set
     for any reason.  *Note Buffer-Local Variables::.

 -- Variable: buffer-save-without-query
     This variable, if non-`nil' in a particular buffer, tells
     `save-buffers-kill-emacs' and `save-some-buffers' to save this
     buffer (if it's modified) without asking the user.  The variable
     automatically becomes buffer-local when set for any reason.

 -- Function: buffer-live-p object
     This function returns `t' if OBJECT is a live buffer (a buffer
     which has not been killed), `nil' otherwise.


File: elisp,  Node: Indirect Buffers,  Next: Swapping Text,  Prev: Killing Buffers,  Up: Buffers

27.11 Indirect Buffers
======================

An "indirect buffer" shares the text of some other buffer, which is
called the "base buffer" of the indirect buffer.  In some ways it is
the analogue, for buffers, of a symbolic link among files.  The base
buffer may not itself be an indirect buffer.

   The text of the indirect buffer is always identical to the text of
its base buffer; changes made by editing either one are visible
immediately in the other.  This includes the text properties as well as
the characters themselves.

   In all other respects, the indirect buffer and its base buffer are
completely separate.  They have different names, independent values of
point, independent narrowing, independent markers and overlays (though
inserting or deleting text in either buffer relocates the markers and
overlays for both), independent major modes, and independent
buffer-local variable bindings.

   An indirect buffer cannot visit a file, but its base buffer can.  If
you try to save the indirect buffer, that actually saves the base
buffer.

   Killing an indirect buffer has no effect on its base buffer.  Killing
the base buffer effectively kills the indirect buffer in that it cannot
ever again be the current buffer.

 -- Command: make-indirect-buffer base-buffer name &optional clone
     This creates and returns an indirect buffer named NAME whose base
     buffer is BASE-BUFFER.  The argument BASE-BUFFER may be a live
     buffer or the name (a string) of an existing buffer.  If NAME is
     the name of an existing buffer, an error is signaled.

     If CLONE is non-`nil', then the indirect buffer originally shares
     the "state" of BASE-BUFFER such as major mode, minor modes, buffer
     local variables and so on.  If CLONE is omitted or `nil' the
     indirect buffer's state is set to the default state for new
     buffers.

     If BASE-BUFFER is an indirect buffer, its base buffer is used as
     the base for the new buffer.  If, in addition, CLONE is non-`nil',
     the initial state is copied from the actual base buffer, not from
     BASE-BUFFER.

 -- Command: clone-indirect-buffer newname display-flag &optional
          norecord
     This function creates and returns a new indirect buffer that shares
     the current buffer's base buffer and copies the rest of the current
     buffer's attributes.  (If the current buffer is not indirect, it is
     used as the base buffer.)

     If DISPLAY-FLAG is non-`nil', that means to display the new buffer
     by calling `pop-to-buffer'.  If NORECORD is non-`nil', that means
     not to put the new buffer to the front of the buffer list.

 -- Function: buffer-base-buffer &optional buffer
     This function returns the base buffer of BUFFER, which defaults to
     the current buffer.  If BUFFER is not indirect, the value is
     `nil'.  Otherwise, the value is another buffer, which is never an
     indirect buffer.


File: elisp,  Node: Swapping Text,  Next: Buffer Gap,  Prev: Indirect Buffers,  Up: Buffers

27.12 Swapping Text Between Two Buffers
=======================================

Specialized modes sometimes need to let the user access from the same
buffer several vastly different types of text.  For example, you may
need to display a summary of the buffer text, in addition to letting
the user access the text itself.

   This could be implemented with multiple buffers (kept in sync when
the user edits the text), or with narrowing (*note Narrowing::).  But
these alternatives might sometimes become tedious or prohibitively
expensive, especially if each type of text requires expensive
buffer-global operations in order to provide correct display and
editing commands.

   Emacs provides another facility for such modes: you can quickly swap
buffer text between two buffers with `buffer-swap-text'.  This function
is very fast because it doesn't move any text, it only changes the
internal data structures of the buffer object to point to a different
chunk of text.  Using it, you can pretend that a group of two or more
buffers are actually a single virtual buffer that holds the contents of
all the individual buffers together.

 -- Function: buffer-swap-text buffer
     This function swaps the text of the current buffer and that of its
     argument BUFFER.  It signals an error if one of the two buffers is
     an indirect buffer (*note Indirect Buffers::) or is a base buffer
     of an indirect buffer.

     All the buffer properties that are related to the buffer text are
     swapped as well: the positions of point and mark, all the markers,
     the overlays, the text properties, the undo list, the value of the
     `enable-multibyte-characters' flag (*note
     enable-multibyte-characters: Text Representations.), etc.

   If you use `buffer-swap-text' on a file-visiting buffer, you should
set up a hook to save the buffer's original text rather than what it
was swapped with.  `write-region-annotate-functions' works for this
purpose.  You should probably set `buffer-saved-size' to -2 in the
buffer, so that changes in the text it is swapped with will not
interfere with auto-saving.


File: elisp,  Node: Buffer Gap,  Prev: Swapping Text,  Up: Buffers

27.13 The Buffer Gap
====================

Emacs buffers are implemented using an invisible "gap" to make
insertion and deletion faster.  Insertion works by filling in part of
the gap, and deletion adds to the gap.  Of course, this means that the
gap must first be moved to the locus of the insertion or deletion.
Emacs moves the gap only when you try to insert or delete.  This is why
your first editing command in one part of a large buffer, after
previously editing in another far-away part, sometimes involves a
noticeable delay.

   This mechanism works invisibly, and Lisp code should never be
affected by the gap's current location, but these functions are
available for getting information about the gap status.

 -- Function: gap-position
     This function returns the current gap position in the current
     buffer.

 -- Function: gap-size
     This function returns the current gap size of the current buffer.


File: elisp,  Node: Windows,  Next: Frames,  Prev: Buffers,  Up: Top

28 Windows
**********

This chapter describes the functions and variables related to Emacs
windows.  *Note Frames::, for how windows are assigned an area of screen
available for Emacs to use.  *Note Display::, for information on how
text is displayed in windows.

* Menu:

* Basic Windows::           Basic information on using windows.
* Windows and Frames::      Relating windows to the frame they appear on.
* Window Sizes::            Accessing a window's size.
* Resizing Windows::        Changing the sizes of windows.
* Splitting Windows::       Splitting one window into two windows.
* Deleting Windows::        Deleting a window gives its space to other windows.
* Selecting Windows::       The selected window is the one that you edit in.
* Cyclic Window Ordering::  Moving around the existing windows.
* Buffers and Windows::     Each window displays the contents of a buffer.
* Switching Buffers::       Higher-level functions for switching to a buffer.
* Choosing Window::         How to choose a window for displaying a buffer.
* Display Action Functions:: Subroutines for `display-buffer'.
* Choosing Window Options:: Extra options affecting how buffers are displayed.
* Window History::          Each window remembers the buffers displayed in it.
* Dedicated Windows::       How to avoid displaying another buffer in
                              a specific window.
* Quitting Windows::        How to restore the state prior to displaying a
                              buffer.
* Window Point::            Each window has its own location of point.
* Window Start and End::    Buffer positions indicating which text is
                              on-screen in a window.
* Textual Scrolling::       Moving text up and down through the window.
* Vertical Scrolling::      Moving the contents up and down on the window.
* Horizontal Scrolling::    Moving the contents sideways on the window.
* Coordinates and Windows:: Converting coordinates to windows.
* Window Configurations::   Saving and restoring the state of the screen.
* Window Parameters::       Associating additional information with windows.
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.


File: elisp,  Node: Basic Windows,  Next: Windows and Frames,  Up: Windows

28.1 Basic Concepts of Emacs Windows
====================================

A "window" is a area of the screen that is used to display a buffer
(*note Buffers::).  In Emacs Lisp, windows are represented by a special
Lisp object type.

   Windows are grouped into frames (*note Frames::).  Each frame
contains at least one window; the user can subdivide it into multiple,
non-overlapping windows to view several buffers at once.  Lisp programs
can use multiple windows for a variety of purposes.  In Rmail, for
example, you can view a summary of message titles in one window, and
the contents of the selected message in another window.

   Emacs uses the word "window" with a different meaning than in
graphical desktop environments and window systems, such as the X Window
System.  When Emacs is run on X, each of its graphical X windows is an
Emacs frame (containing one or more Emacs windows).  When Emacs is run
on a text terminal, the frame fills the entire terminal screen.

   Unlike X windows, Emacs windows are "tiled"; they never overlap
within the area of the frame.  When a window is created, resized, or
deleted, the change in window space is taken from or given to the
adjacent windows, so that the total area of the frame is unchanged.

   A "live window" is one that is actually displaying a buffer in a
frame.  Such a window can be "deleted", i.e. removed from the frame
(*note Deleting Windows::); then it is no longer live, but the Lisp
object representing it might be still referenced from other Lisp
objects.  A deleted window may be brought back to life by restoring a
saved window configuration (*note Window Configurations::).

 -- Function: windowp object
     This function returns `t' if OBJECT is a window (whether or not it
     is live).  Otherwise, it returns `nil'.

 -- Function: window-live-p object
     This function returns `t' if OBJECT is a live window and `nil'
     otherwise.  A live window is one that displays a buffer.

   The windows in each frame are organized into a "window tree".  *Note
Windows and Frames::.  The leaf nodes of each window tree are live
windows--the ones actually displaying buffers.  The internal nodes of
the window tree are internal windows, which are not live.  You can
distinguish internal windows from deleted windows with `window-valid-p'.

 -- Function: window-valid-p object
     This function returns `t' if OBJECT is a live window, or an
     internal window in a window tree.  Otherwise, it returns `nil',
     including for the case where OBJECT is a deleted window.

   In each frame, at any time, exactly one Emacs window is designated
as "selected within the frame".  For the selected frame, that window is
called the "selected window"--the one in which most editing takes
place, and in which the cursor for selected windows appears (*note
Cursor Parameters::).  The selected window's buffer is usually also the
current buffer, except when `set-buffer' has been used (*note Current
Buffer::).  As for non-selected frames, the window selected within the
frame becomes the selected window if the frame is ever selected.  *Note
Selecting Windows::.

 -- Function: selected-window
     This function returns the selected window (which is always a live
     window).


File: elisp,  Node: Windows and Frames,  Next: Window Sizes,  Prev: Basic Windows,  Up: Windows

28.2 Windows and Frames
=======================

Each window belongs to exactly one frame (*note Frames::).

 -- Function: window-frame window
     This function returns the frame that the window WINDOW belongs to.
     If WINDOW is `nil', it defaults to the selected window.

 -- Function: window-list &optional frame minibuffer window
     This function returns a list of live windows belonging to the frame
     FRAME.  If FRAME is omitted or `nil', it defaults to the selected
     frame.

     The optional argument MINIBUFFER specifies whether to include the
     minibuffer window in the returned list.  If MINIBUFFER is `t', the
     minibuffer window is included.  If MINIBUFFER is `nil' or omitted,
     the minibuffer window is included only if it is active.  If
     MINIBUFFER is neither `nil' nor `t', the minibuffer window is
     never included.

     The optional argument WINDOW, if non-`nil', should be a live
     window on the specified frame; then WINDOW will be the first
     element in the returned list.  If WINDOW is omitted or `nil', the
     window selected within the frame is the first element.

   Windows in the same frame are organized into a "window tree", whose
leaf nodes are the live windows.  The internal nodes of a window tree
are not live; they exist for the purpose of organizing the
relationships between live windows.  The root node of a window tree is
called the "root window".  It can be either a live window (if the frame
has just one window), or an internal window.

   A minibuffer window (*note Minibuffer Windows::) is not part of its
frame's window tree unless the frame is a minibuffer-only frame.
Nonetheless, most of the functions in this section accept the
minibuffer window as an argument.  Also, the function `window-tree'
described at the end of this section lists the minibuffer window
alongside the actual window tree.

 -- Function: frame-root-window &optional frame-or-window
     This function returns the root window for FRAME-OR-WINDOW.  The
     argument FRAME-OR-WINDOW should be either a window or a frame; if
     omitted or `nil', it defaults to the selected frame.  If
     FRAME-OR-WINDOW is a window, the return value is the root window
     of that window's frame.

   When a window is split, there are two live windows where previously
there was one.  One of these is represented by the same Lisp window
object as the original window, and the other is represented by a
newly-created Lisp window object.  Both of these live windows become
leaf nodes of the window tree, as "child windows" of a single internal
window.  If necessary, Emacs automatically creates this internal
window, which is also called the "parent window", and assigns it to the
appropriate position in the window tree.  A set of windows that share
the same parent are called "siblings".

 -- Function: window-parent &optional window
     This function returns the parent window of WINDOW.  If WINDOW is
     omitted or `nil', it defaults to the selected window.  The return
     value is `nil' if WINDOW has no parent (i.e. it is a minibuffer
     window or the root window of its frame).

   Each internal window always has at least two child windows.  If this
number falls to one as a result of window deletion, Emacs automatically
deletes the internal window, and its sole remaining child window takes
its place in the window tree.

   Each child window can be either a live window, or an internal window
(which in turn would have its own child windows).  Therefore, each
internal window can be thought of as occupying a certain rectangular
"screen area"--the union of the areas occupied by the live windows that
are ultimately descended from it.

   For each internal window, the screen areas of the immediate children
are arranged either vertically or horizontally (never both).  If the
child windows are arranged one above the other, they are said to form a
"vertical combination"; if they are arranged side by side, they are
said to form a "horizontal combination".  Consider the following
example:

          ______________________________________
         | ______  ____________________________ |
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||____________W4____________|||
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||____________W5____________|||
         ||__W2__||_____________W3_____________ |
         |__________________W1__________________|

The root window of this frame is an internal window, `W1'.  Its child
windows form a horizontal combination, consisting of the live window
`W2' and the internal window `W3'.  The child windows of `W3' form a
vertical combination, consisting of the live windows `W4' and `W5'.
Hence, the live windows in this window tree are `W2' `W4', and `W5'.

   The following functions can be used to retrieve a child window of an
internal window, and the siblings of a child window.

 -- Function: window-top-child window
     This function returns the topmost child window of WINDOW, if
     WINDOW is an internal window whose children form a vertical
     combination.  For any other type of window, the return value is
     `nil'.

 -- Function: window-left-child window
     This function returns the leftmost child window of WINDOW, if
     WINDOW is an internal window whose children form a horizontal
     combination.  For any other type of window, the return value is
     `nil'.

 -- Function: window-child window
     This function returns the first child window of the internal window
     WINDOW--the topmost child window for a vertical combination, or
     the leftmost child window for a horizontal combination.  If WINDOW
     is a live window, the return value is `nil'.

 -- Function: window-combined-p &optional window horizontal
     This function returns a non-`nil' value if and only if WINDOW is
     part of a vertical combination.  If WINDOW is omitted or `nil', it
     defaults to the selected one.

     If the optional argument HORIZONTAL is non-`nil', this means to
     return non-`nil' if and only if WINDOW is part of a horizontal
     combination.

 -- Function: window-next-sibling &optional window
     This function returns the next sibling of the window WINDOW.  If
     omitted or `nil', WINDOW defaults to the selected window.  The
     return value is `nil' if WINDOW is the last child of its parent.

 -- Function: window-prev-sibling &optional window
     This function returns the previous sibling of the window WINDOW.
     If omitted or `nil', WINDOW defaults to the selected window.  The
     return value is `nil' if WINDOW is the first child of its parent.

   The functions `window-next-sibling' and `window-prev-sibling' should
not be confused with the functions `next-window' and `previous-window',
which return the next and previous window, respectively, in the cyclic
ordering of windows (*note Cyclic Window Ordering::).

   You can use the following functions to find the first live window on
a frame, and to retrieve the entire window tree of a frame:

 -- Function: frame-first-window &optional frame-or-window
     This function returns the live window at the upper left corner of
     the frame specified by FRAME-OR-WINDOW.  The argument
     FRAME-OR-WINDOW must denote a window or a live frame and defaults
     to the selected frame.  If FRAME-OR-WINDOW specifies a window,
     this function returns the first window on that window's frame.
     Under the assumption that the frame from our canonical example is
     selected `(frame-first-window)' returns `W2'.

 -- Function: window-tree &optional frame
     This function returns a list representing the window tree for frame
     FRAME.  If FRAME is omitted or `nil', it defaults to the selected
     frame.

     The return value is a list of the form `(ROOT MINI)', where ROOT
     represents the window tree of the frame's root window, and MINI is
     the frame's minibuffer window.

     If the root window is live, ROOT is that window itself.
     Otherwise, ROOT is a list `(DIR EDGES W1 W2 ...)' where DIR is
     `nil' for a horizontal combination and `t' for a vertical
     combination, EDGES gives the size and position of the combination,
     and the remaining elements are the child windows.  Each child
     window may again be a window object (for a live window) or a list
     with the same format as above (for an internal window).  The EDGES
     element is a list `(LEFT TOP RIGHT BOTTOM)', similar to the value
     returned by `window-edges' (*note Coordinates and Windows::).


File: elisp,  Node: Window Sizes,  Next: Resizing Windows,  Prev: Windows and Frames,  Up: Windows

28.3 Window Sizes
=================

The following schematic shows the structure of a live window:

              _________________________________________
           ^ |______________ Header Line_______________|
           | |LS|LF|LM|                       |RM|RF|RS| ^
           | |  |  |  |                       |  |  |  | |
      Window |  |  |  |       Text Area       |  |  |  | Window
      Total  |  |  |  |     (Window Body)     |  |  |  | Body
      Height |  |  |  |                       |  |  |  | Height
           | |  |  |  |<- Window Body Width ->|  |  |  | |
           | |__|__|__|_______________________|__|__|__| v
           v |_______________ Mode Line _______________|

              <----------- Window Total Width -------->

   At the center of the window is the "text area", or "body", where the
buffer text is displayed.  On each side of the text area is a series of
vertical areas; from innermost to outermost, these are the left and
right margins, denoted by LM and RM in the schematic (*note Display
Margins::); the left and right fringes, denoted by LF and RF (*note
Fringes::); and the left or right scroll bar, only one of which is
present at any time, denoted by LS and RS (*note Scroll Bars::).  At
the top of the window is an optional header line (*note Header
Lines::), and at the bottom of the window is the mode line (*note Mode
Line Format::).

   Emacs provides several functions for finding the height and width of
a window.  Except where noted, Emacs reports window heights and widths
as integer numbers of lines and columns, respectively.  On a graphical
display, each "line" and "column" actually corresponds to the height
and width of a "default" character specified by the frame's default
font.  Thus, if a window is displaying text with a different font or
size, the reported height and width for that window may differ from the
actual number of text lines or columns displayed within it.

   The "total height" of a window is the distance between the top and
bottom of the window, including the header line (if one exists) and the
mode line.  The "total width" of a window is the distance between the
left and right edges of the mode line.  Note that the height of a frame
is not the same as the height of its windows, since a frame may also
contain an echo area, menu bar, and tool bar (*note Size and
Position::).

 -- Function: window-total-height &optional window
     This function returns the total height, in lines, of the window
     WINDOW.  If WINDOW is omitted or `nil', it defaults to the
     selected window.  If WINDOW is an internal window, the return
     value is the total height occupied by its descendant windows.

 -- Function: window-total-width &optional window
     This function returns the total width, in columns, of the window
     WINDOW.  If WINDOW is omitted or `nil', it defaults to the
     selected window.  If WINDOW is internal, the return value is the
     total width occupied by its descendant windows.

 -- Function: window-total-size &optional window horizontal
     This function returns either the total height or width of the
     window WINDOW.  If HORIZONTAL is omitted or `nil', this is
     equivalent to calling `window-total-height' for WINDOW; otherwise
     it is equivalent to calling `window-total-width' for WINDOW.

   The following functions can be used to determine whether a given
window has any adjacent windows.

 -- Function: window-full-height-p &optional window
     This function returns non-`nil' if WINDOW has no other window
     above or below it in its frame, i.e. its total height equals the
     total height of the root window on that frame.  If WINDOW is
     omitted or `nil', it defaults to the selected window.

 -- Function: window-full-width-p &optional window
     This function returns non-`nil' if WINDOW has no other window to
     the left or right in its frame, i.e. its total width equals that
     of the root window on that frame.  If WINDOW is omitted or `nil',
     it defaults to the selected window.

   The "body height" of a window is the height of its text area, which
does not include the mode or header line.  Similarly, the "body width"
is the width of the text area, which does not include the scroll bar,
fringes, or margins.

 -- Function: window-body-height &optional window
     This function returns the body height, in lines, of the window
     WINDOW.  If WINDOW is omitted or `nil', it defaults to the
     selected window; otherwise it must be a live window.

     If there is a partially-visible line at the bottom of the text
     area, that counts as a whole line; to exclude such a
     partially-visible line, use `window-text-height', below.

 -- Function: window-body-width &optional window
     This function returns the body width, in columns, of the window
     WINDOW.  If WINDOW is omitted or `nil', it defaults to the
     selected window; otherwise it must be a live window.

 -- Function: window-body-size &optional window horizontal
     This function returns the body height or body width of WINDOW.  If
     HORIZONTAL is omitted or `nil', it is equivalent to calling
     `window-body-height' for WINDOW; otherwise it is equivalent to
     calling `window-body-width'.

 -- Function: window-text-height &optional window
     This function is like `window-body-height', except that any
     partially-visible line at the bottom of the text area is not
     counted.

   For compatibility with previous versions of Emacs, `window-height'
is an alias for `window-total-height', and `window-width' is an alias
for `window-body-width'.  These aliases are considered obsolete and
will be removed in the future.

   Commands that change the size of windows (*note Resizing Windows::),
or split them (*note Splitting Windows::), obey the variables
`window-min-height' and `window-min-width', which specify the smallest
allowable window height and width.  *Note Deleting and Rearranging
Windows: (emacs)Change Window.  They also obey the variable
`window-size-fixed', with which a window can be "fixed" in size:

 -- Variable: window-size-fixed
     If this buffer-local variable is non-`nil', the size of any window
     displaying the buffer cannot normally be changed.  Deleting a
     window or changing the frame's size may still change its size, if
     there is no choice.

     If the value is `height', then only the window's height is fixed;
     if the value is `width', then only the window's width is fixed.
     Any other non-`nil' value fixes both the width and the height.

 -- Function: window-size-fixed-p &optional window horizontal
     This function returns a non-`nil' value if WINDOW's height is
     fixed.  If WINDOW is omitted or `nil', it defaults to the selected
     window.  If the optional argument HORIZONTAL is non-`nil', the
     return value is non-`nil' if WINDOW's width is fixed.

     A `nil' return value does not necessarily mean that WINDOW can be
     resized in the desired direction.  To determine that, use the
     function `window-resizable'.  *Note Resizing Windows::.

   *Note Coordinates and Windows::, for more functions that report the
positions of various parts of a window relative to the frame, from
which you can calculate its size.  In particular, you can use the
functions `window-pixel-edges' and `window-inside-pixel-edges' to find
the size in pixels, for graphical displays.


File: elisp,  Node: Resizing Windows,  Next: Splitting Windows,  Prev: Window Sizes,  Up: Windows

28.4 Resizing Windows
=====================

This section describes functions for resizing a window without changing
the size of its frame.  Because live windows do not overlap, these
functions are meaningful only on frames that contain two or more
windows: resizing a window also changes the size of a neighboring
window.  If there is just one window on a frame, its size cannot be
changed except by resizing the frame (*note Size and Position::).

   Except where noted, these functions also accept internal windows as
arguments.  Resizing an internal window causes its child windows to be
resized to fit the same space.

 -- Function: window-resizable window delta &optional horizontal ignore
     This function returns DELTA if the size of WINDOW can be changed
     vertically by DELTA lines.  If the optional argument HORIZONTAL is
     non-`nil', it instead returns DELTA if WINDOW can be resized
     horizontally by DELTA columns.  It does not actually change the
     window size.

     If WINDOW is `nil', it defaults to the selected window.

     A positive value of DELTA means to check whether the window can be
     enlarged by that number of lines or columns; a negative value of
     DELTA means to check whether the window can be shrunk by that many
     lines or columns.  If DELTA is non-zero, a return value of 0 means
     that the window cannot be resized.

     Normally, the variables `window-min-height' and `window-min-width'
     specify the smallest allowable window size.  *Note Deleting and
     Rearranging Windows: (emacs)Change Window.  However, if the
     optional argument IGNORE is non-`nil', this function ignores
     `window-min-height' and `window-min-width', as well as
     `window-size-fixed'.  Instead, it considers the minimum-height
     window to be one consisting of a header (if any), a mode line,
     plus a text area one line tall; and a minimum-width window as one
     consisting of fringes, margins, and scroll bar (if any), plus a
     text area two columns wide.

 -- Function: window-resize window delta &optional horizontal ignore
     This function resizes WINDOW by DELTA increments.  If HORIZONTAL
     is `nil', it changes the height by DELTA lines; otherwise, it
     changes the width by DELTA columns.  A positive DELTA means to
     enlarge the window, and a negative DELTA means to shrink it.

     If WINDOW is `nil', it defaults to the selected window.  If the
     window cannot be resized as demanded, an error is signaled.

     The optional argument IGNORE has the same meaning as for the
     function `window-resizable' above.

     The choice of which window edges this function alters depends on
     the values of the option `window-combination-resize' and the
     combination limits of the involved windows; in some cases, it may
     alter both edges.  *Note Splitting Windows::.  To resize by moving
     only the bottom or right edge of a window, use the function
     `adjust-window-trailing-edge', below.

 -- Function: adjust-window-trailing-edge window delta &optional
          horizontal
     This function moves WINDOW's bottom edge by DELTA lines.  If
     optional argument HORIZONTAL is non-`nil', it instead moves the
     right edge by DELTA columns.  If WINDOW is `nil', it defaults to
     the selected window.

     A positive DELTA moves the edge downwards or to the right; a
     negative DELTA moves it upwards or to the left.  If the edge
     cannot be moved as far as specified by DELTA, this function moves
     it as far as possible but does not signal a error.

     This function tries to resize windows adjacent to the edge that is
     moved.  If this is not possible for some reason (e.g. if that
     adjacent window is fixed-size), it may resize other windows.

   The following commands resize windows in more specific ways.  When
called interactively, they act on the selected window.

 -- Command: fit-window-to-buffer &optional window max-height
          min-height override
     This command adjusts the height of WINDOW to fit the text in it.
     It returns non-`nil' if it was able to resize WINDOW, and `nil'
     otherwise.  If WINDOW is omitted or `nil', it defaults to the
     selected window.  Otherwise, it should be a live window.

     The optional argument MAX-HEIGHT, if non-`nil', specifies the
     maximum total height that this function can give WINDOW.  The
     optional argument MIN-HEIGHT, if non-`nil', specifies the minimum
     total height that it can give, which overrides the variable
     `window-min-height'.

     If the optional argument OVERRIDE is non-`nil', this function
     ignores any size restrictions imposed by `window-min-height' and
     `window-min-width'.

 -- Command: shrink-window-if-larger-than-buffer &optional window
     This command attempts to reduce WINDOW's height as much as
     possible while still showing its full buffer, but no less than
     `window-min-height' lines.  The return value is non-`nil' if the
     window was resized, and `nil' otherwise.  If WINDOW is omitted or
     `nil', it defaults to the selected window.  Otherwise, it should
     be a live window.

     This command does nothing if the window is already too short to
     display all of its buffer, or if any of the buffer is scrolled
     off-screen, or if the window is the only live window in its frame.

 -- Command: balance-windows &optional window-or-frame
     This function balances windows in a way that gives more space to
     full-width and/or full-height windows.  If WINDOW-OR-FRAME
     specifies a frame, it balances all windows on that frame.  If
     WINDOW-OR-FRAME specifies a window, it balances only that window
     and its siblings (*note Windows and Frames::).

 -- Command: balance-windows-area
     This function attempts to give all windows on the selected frame
     approximately the same share of the screen area.  Full-width or
     full-height windows are not given more space than other windows.

 -- Command: maximize-window &optional window
     This function attempts to make WINDOW as large as possible, in
     both dimensions, without resizing its frame or deleting other
     windows.  If WINDOW is omitted or `nil', it defaults to the
     selected window.

 -- Command: minimize-window &optional window
     This function attempts to make WINDOW as small as possible, in
     both dimensions, without deleting it or resizing its frame.  If
     WINDOW is omitted or `nil', it defaults to the selected window.


File: elisp,  Node: Splitting Windows,  Next: Deleting Windows,  Prev: Resizing Windows,  Up: Windows

28.5 Splitting Windows
======================

This section describes functions for creating a new window by
"splitting" an existing one.

 -- Command: split-window &optional window size side
     This function creates a new live window next to the window WINDOW.
     If WINDOW is omitted or `nil', it defaults to the selected window.
     That window is "split", and reduced in size.  The space is taken
     up by the new window, which is returned.

     The optional second argument SIZE determines the sizes of WINDOW
     and/or the new window.  If it is omitted or `nil', both windows
     are given equal sizes; if there is an odd line, it is allocated to
     the new window.  If SIZE is a positive number, WINDOW is given
     SIZE lines (or columns, depending on the value of SIDE).  If SIZE
     is a negative number, the new window is given -SIZE lines (or
     columns).

     If SIZE is `nil', this function obeys the variables
     `window-min-height' and `window-min-width'.  *Note Deleting and
     Rearranging Windows: (emacs)Change Window.  Thus, it signals an
     error if splitting would result in making a window smaller than
     those variables specify.  However, a non-`nil' value for SIZE
     causes those variables to be ignored; in that case, the smallest
     allowable window is considered to be one that has space for a text
     area one line tall and/or two columns wide.

     The optional third argument SIDE determines the position of the
     new window relative to WINDOW.  If it is `nil' or `below', the new
     window is placed below WINDOW.  If it is `above', the new window
     is placed above WINDOW.  In both these cases, SIZE specifies a
     total window height, in lines.

     If SIDE is `t' or `right', the new window is placed on the right
     of WINDOW.  If SIDE is `left', the new window is placed on the
     left of WINDOW.  In both these cases, SIZE specifies a total
     window width, in columns.

     If WINDOW is a live window, the new window inherits various
     properties from it, including margins and scroll bars.  If WINDOW
     is an internal window, the new window inherits the properties of
     the window selected within WINDOW's frame.

     The behavior of this function may be altered by the window
     parameters of WINDOW, so long as the variable
     `ignore-window-parameters' is `nil'.  If the value of the
     `split-window' window parameter is `t', this function ignores all
     other window parameters.  Otherwise, if the value of the
     `split-window' window parameter is a function, that function is
     called with the arguments WINDOW, SIZE, and SIDE, in lieu of the
     usual action of `split-window'.  Otherwise, this function obeys
     the `window-atom' or `window-side' window parameter, if any.
     *Note Window Parameters::.

   As an example, here is a sequence of `split-window' calls that
yields the window configuration discussed in *note Windows and Frames::.
This example demonstrates splitting a live window as well as splitting
an internal window.  We begin with a frame containing a single window
(a live root window), which we denote by W4.  Calling `(split-window
W4)' yields this window configuration:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W4_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W5_________________||
         |__________________W3__________________|

The `split-window' call has created a new live window, denoted by W5.
It has also created a new internal window, denoted by W3, which becomes
the root window and the parent of both W4 and W5.

   Next, we call `(split-window W3 nil 'left)', passing the internal
window W3 as the argument.  The result:

          ______________________________________
         | ______  ____________________________ |
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||____________W4____________|||
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||____________W5____________|||
         ||__W2__||_____________W3_____________ |
         |__________________W1__________________|

A new live window W2 is created, to the left of the internal window W3.
A new internal window W1 is created, becoming the new root window.

 -- User Option: window-combination-resize
     If this variable is `nil', `split-window' can only split a window
     (denoted by WINDOW) if WINDOW's screen area is large enough to
     accommodate both itself and the new window.

     If this variable is `t', `split-window' tries to resize all
     windows that are part of the same combination as WINDOW, in order
     to accommodate the new window.  In particular, this may allow
     `split-window' to succeed even if WINDOW is a fixed-size window or
     too small to ordinarily split.  Furthermore, subsequently resizing
     or deleting WINDOW may resize all other windows in its combination.

     The default is `nil'.  Other values are reserved for future use.
     The value of this variable is ignored when
     `window-combination-limit' is non-`nil' (see below).

   To illustrate the effect of `window-combination-resize', consider
the following window configuration:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

If `window-combination-resize' is `nil', splitting window `W3' leaves
the size of `W2' unchanged:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W3_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W4_________________||
         |__________________W1__________________|

If `window-combination-resize' is `t', splitting `W3' instead leaves
all three live windows with approximately the same height:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W4_________________||
         |__________________W1__________________|

 -- User Option: window-combination-limit
     If the value of this variable is `t', the `split-window' function
     always creates a new internal window.  If the value is `nil', the
     new live window is allowed to share the existing parent window, if
     one exists, provided the split occurs in the same direction as the
     existing window combination (otherwise, a new internal window is
     created anyway).  The default is `nil'.  Other values are reserved
     for future use.

     Thus, if the value of this variable is at all times `t', then at
     all times every window tree is a binary tree (a tree where each
     window except the root window has exactly one sibling).

     Furthermore, `split-window' calls `set-window-combination-limit'
     on the newly-created internal window, recording the current value
     of this variable.  This affects how the window tree is rearranged
     when the child windows are deleted (see below).

 -- Function: set-window-combination-limit window limit
     This functions sets the "combination limit" of the window WINDOW
     to LIMIT.  This value can be retrieved via the function
     `window-combination-limit'.  See below for its effects; note that
     it is only meaningful for internal windows.  The `split-window'
     function automatically calls this function, passing the value of
     the variable `window-combination-limit' as LIMIT.

 -- Function: window-combination-limit window
     This function returns the combination limit for WINDOW.

     The combination limit is meaningful only for an internal window.
     If it is `nil', then Emacs is allowed to automatically delete
     WINDOW, in response to a window deletion, in order to group the
     child windows of WINDOW with its sibling windows to form a new
     window combination.  If the combination limit is `t', the child
     windows of WINDOW are never automatically re-combined with its
     siblings.

   To illustrate the effect of `window-combination-limit', consider the
following configuration (throughout this example, we will assume that
`window-combination-resize' is `nil'):

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

If `window-combination-limit' is `nil', splitting `W2' into two
windows, one above the other, yields

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W4_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

The newly-created window, `W4', shares the same internal window `W1'.
If `W4' is resized, it is allowed to resize the other live window, `W3'.

   If `window-combination-limit' is `t', splitting `W2' in the initial
configuration would instead have produced this:

          ______________________________________
         | ____________________________________ |
         || __________________________________ ||
         |||                                  |||
         |||________________W2________________|||
         || __________________________________ ||
         |||                                  |||
         |||________________W4________________|||
         ||_________________W5_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

A new internal window `W5' has been created; its children are `W2' and
the new live window `W4'.  Now, `W2' is the only sibling of `W4', so
resizing `W4' will resize `W2', leaving `W3' unaffected.

   For interactive use, Emacs provides two commands which always split
the selected window.  These call `split-window' internally.

 -- Command: split-window-right &optional size
     This function splits the selected window into two side-by-side
     windows, putting the selected window on the left.  If SIZE is
     positive, the left window gets SIZE columns; if SIZE is negative,
     the right window gets -SIZE columns.

 -- Command: split-window-below &optional size
     This function splits the selected window into two windows, one
     above the other, leaving the upper window selected.  If SIZE is
     positive, the upper window gets SIZE lines; if SIZE is negative,
     the lower window gets -SIZE lines.

 -- User Option: split-window-keep-point
     If the value of this variable is non-`nil' (the default),
     `split-window-below' behaves as described above.

     If it is `nil', `split-window-below' adjusts point in each of the
     two windows to minimize redisplay.  (This is useful on slow
     terminals.)  It selects whichever window contains the screen line
     that point was previously on.  Note that this only affects
     `split-window-below', not the lower-level `split-window' function.


File: elisp,  Node: Deleting Windows,  Next: Selecting Windows,  Prev: Splitting Windows,  Up: Windows

28.6 Deleting Windows
=====================

"Deleting" a window removes it from the frame's window tree.  If the
window is a live window, it disappears from the screen.  If the window
is an internal window, its child windows are deleted too.

   Even after a window is deleted, it continues to exist as a Lisp
object, until there are no more references to it.  Window deletion can
be reversed, by restoring a saved window configuration (*note Window
Configurations::).

 -- Command: delete-window &optional window
     This function removes WINDOW from display and returns `nil'.  If
     WINDOW is omitted or `nil', it defaults to the selected window.
     If deleting the window would leave no more windows in the window
     tree (e.g. if it is the only live window in the frame), an error
     is signaled.

     By default, the space taken up by WINDOW is given to one of its
     adjacent sibling windows, if any.  However, if the variable
     `window-combination-resize' is non-`nil', the space is
     proportionally distributed among any remaining windows in the
     window combination.  *Note Splitting Windows::.

     The behavior of this function may be altered by the window
     parameters of WINDOW, so long as the variable
     `ignore-window-parameters' is `nil'.  If the value of the
     `delete-window' window parameter is `t', this function ignores all
     other window parameters.  Otherwise, if the value of the
     `delete-window' window parameter is a function, that function is
     called with the argument WINDOW, in lieu of the usual action of
     `delete-window'.  Otherwise, this function obeys the `window-atom'
     or `window-side' window parameter, if any.  *Note Window
     Parameters::.

 -- Command: delete-other-windows &optional window
     This function makes WINDOW fill its frame, by deleting other
     windows as necessary.  If WINDOW is omitted or `nil', it defaults
     to the selected window.  The return value is `nil'.

     The behavior of this function may be altered by the window
     parameters of WINDOW, so long as the variable
     `ignore-window-parameters' is `nil'.  If the value of the
     `delete-other-windows' window parameter is `t', this function
     ignores all other window parameters.  Otherwise, if the value of
     the `delete-other-windows' window parameter is a function, that
     function is called with the argument WINDOW, in lieu of the usual
     action of `delete-other-windows'.  Otherwise, this function obeys
     the `window-atom' or `window-side' window parameter, if any.
     *Note Window Parameters::.

 -- Command: delete-windows-on &optional buffer-or-name frame
     This function deletes all windows showing BUFFER-OR-NAME, by
     calling `delete-window' on those windows.  BUFFER-OR-NAME should
     be a buffer, or the name of a buffer; if omitted or `nil', it
     defaults to the current buffer.  If there are no windows showing
     the specified buffer, this function does nothing.  If the specified
     buffer is a minibuffer, an error is signaled.

     If there is a dedicated window showing the buffer, and that window
     is the only one on its frame, this function also deletes that
     frame if it is not the only frame on the terminal.

     The optional argument FRAME specifies which frames to operate on:

        * `nil' means operate on all frames.

        * `t' means operate on the selected frame.

        * `visible' means operate on all visible frames.

        * `0' means operate on all visible or iconified frames.

        * A frame means operate on that frame.

     Note that this argument does not have the same meaning as in other
     functions which scan all live windows (*note Cyclic Window
     Ordering::).  Specifically, the meanings of `t' and `nil' here are
     the opposite of what they are in those other functions.


File: elisp,  Node: Selecting Windows,  Next: Cyclic Window Ordering,  Prev: Deleting Windows,  Up: Windows

28.7 Selecting Windows
======================

 -- Function: select-window window &optional norecord
     This function makes WINDOW the selected window, as well as the
     window selected within its frame (*note Basic Windows::).  WINDOW
     must be a live window.  Unless WINDOW already is the selected
     window, its buffer becomes the current buffer (*note Buffers and
     Windows::).  The return value is WINDOW.

     By default, this function also moves WINDOW's selected buffer to
     the front of the buffer list (*note The Buffer List::), and makes
     WINDOW the most recently selected window.  However, if the
     optional argument NORECORD is non-`nil', these additional actions
     are omitted.

   The sequence of calls to `select-window' with a non-`nil' NORECORD
argument determines an ordering of windows by their selection time.
The function `get-lru-window' can be used to retrieve the least
recently selected live window (*note Cyclic Window Ordering::).

 -- Macro: save-selected-window forms...
     This macro records the selected frame, as well as the selected
     window of each frame, executes FORMS in sequence, then restores the
     earlier selected frame and windows.  It also saves and restores the
     current buffer.  It returns the value of the last form in FORMS.

     This macro does not save or restore anything about the sizes,
     arrangement or contents of windows; therefore, if FORMS change
     them, the change persists.  If the previously selected window of
     some frame is no longer live at the time of exit from FORMS, that
     frame's selected window is left alone.  If the previously selected
     window is no longer live, then whatever window is selected at the
     end of FORMS remains selected.  The current buffer is restored if
     and only if it is still live when exiting FORMS.

     This macro changes neither the ordering of recently selected
     windows nor the buffer list.

 -- Macro: with-selected-window window forms...
     This macro selects WINDOW, executes FORMS in sequence, then
     restores the previously selected window and current buffer.  The
     ordering of recently selected windows and the buffer list remain
     unchanged unless you deliberately change them within FORMS; for
     example, by calling `select-window' with argument NORECORD `nil'.

     This macro does not change the order of recently selected windows
     or the buffer list.

 -- Function: frame-selected-window &optional frame
     This function returns the window on FRAME that is selected within
     that frame.  FRAME should be a live frame; if omitted or `nil', it
     defaults to the selected frame.

 -- Function: set-frame-selected-window frame window &optional norecord
     This function makes WINDOW the window selected within the frame
     FRAME.  FRAME should be a live frame; if omitted or `nil', it
     defaults to the selected frame.  WINDOW should be a live window;
     if omitted or `nil', it defaults to the selected window.

     If FRAME is the selected frame, this makes WINDOW the selected
     window.

     If the optional argument NORECORD is non-`nil', this function does
     not alter the list of most recently selected windows, nor the
     buffer list.


File: elisp,  Node: Cyclic Window Ordering,  Next: Buffers and Windows,  Prev: Selecting Windows,  Up: Windows

28.8 Cyclic Ordering of Windows
===============================

When you use the command `C-x o' (`other-window') to select some other
window, it moves through live windows in a specific order.  For any
given configuration of windows, this order never varies.  It is called
the "cyclic ordering of windows".

   The ordering is determined by a depth-first traversal of the frame's
window tree, retrieving the live windows which are the leaf nodes of
the tree (*note Windows and Frames::).  If the minibuffer is active,
the minibuffer window is included too.  The ordering is cyclic, so the
last window in the sequence is followed by the first one.

 -- Function: next-window &optional window minibuf all-frames
     This function returns a live window, the one following WINDOW in
     the cyclic ordering of windows.  WINDOW should be a live window;
     if omitted or `nil', it defaults to the selected window.

     The optional argument MINIBUF specifies whether minibuffer windows
     should be included in the cyclic ordering.  Normally, when MINIBUF
     is `nil', a minibuffer window is included only if it is currently
     "active"; this matches the behavior of `C-x o'.  (Note that a
     minibuffer window is active as long as its minibuffer is in use;
     see *note Minibuffers::).

     If MINIBUF is `t', the cyclic ordering includes all minibuffer
     windows.  If MINIBUF is neither `t' nor `nil', minibuffer windows
     are not included even if they are active.

     The optional argument ALL-FRAMES specifies which frames to
     consider:

        * `nil' means to consider windows on WINDOW's frame.  If the
          minibuffer window is considered (as specified by the MINIBUF
          argument), then frames that share the minibuffer window are
          considered too.

        * `t' means to consider windows on all existing frames.

        * `visible' means to consider windows on all visible frames.

        * 0 means to consider windows on all visible or iconified
          frames.

        * A frame means to consider windows on that specific frame.

        * Anything else means to consider windows on WINDOW's frame,
          and no others.

     If more than one frame is considered, the cyclic ordering is
     obtained by appending the orderings for those frames, in the same
     order as the list of all live frames (*note Finding All Frames::).

 -- Function: previous-window &optional window minibuf all-frames
     This function returns a live window, the one preceding WINDOW in
     the cyclic ordering of windows.  The other arguments are handled
     like in `next-window'.

 -- Command: other-window count &optional all-frames
     This function selects a live window, one COUNT places from the
     selected window in the cyclic ordering of windows.  If COUNT is a
     positive number, it skips COUNT windows forwards; if COUNT is
     negative, it skips -COUNT windows backwards; if COUNT is zero,
     that simply re-selects the selected window.  When called
     interactively, COUNT is the numeric prefix argument.

     The optional argument ALL-FRAMES has the same meaning as in
     `next-window', like a `nil' MINIBUF argument to `next-window'.

     This function does not select a window that has a non-`nil'
     `no-other-window' window parameter (*note Window Parameters::).

 -- Function: walk-windows fun &optional minibuf all-frames
     This function calls the function FUN once for each live window,
     with the window as the argument.

     It follows the cyclic ordering of windows.  The optional arguments
     MINIBUF and ALL-FRAMES specify the set of windows included; these
     have the same arguments as in `next-window'.  If ALL-FRAMES
     specifies a frame, the first window walked is the first window on
     that frame (the one returned by `frame-first-window'), not
     necessarily the selected window.

     If FUN changes the window configuration by splitting or deleting
     windows, that does not alter the set of windows walked, which is
     determined prior to calling FUN for the first time.

 -- Function: one-window-p &optional no-mini all-frames
     This function returns `t' if the selected window is the only live
     window, and `nil' otherwise.

     If the minibuffer window is active, it is normally considered (so
     that this function returns `nil').  However, if the optional
     argument NO-MINI is non-`nil', the minibuffer window is ignored
     even if active.  The optional argument ALL-FRAMES has the same
     meaning as for `next-window'.

   The following functions return a window which satisfies some
criterion, without selecting it:

 -- Function: get-lru-window &optional all-frames dedicated
     This function returns a live window which is heuristically the
     "least recently used" window.  The optional argument ALL-FRAMES has
     the same meaning as in `next-window'.

     If any full-width windows are present, only those windows are
     considered.  The selected window is never returned, unless it is
     the only candidate.  A minibuffer window is never a candidate.  A
     dedicated window (*note Dedicated Windows::) is never a candidate
     unless the optional argument DEDICATED is non-`nil'.

 -- Function: get-largest-window &optional all-frames dedicated
     This function returns the window with the largest area (height
     times width).  A minibuffer window is never a candidate.  A
     dedicated window (*note Dedicated Windows::) is never a candidate
     unless the optional argument DEDICATED is non-`nil'.

     If there are two candidate windows of the same size, this function
     prefers the one that comes first in the cyclic ordering of windows,
     starting from the selected window.

     The optional argument ALL-FRAMES specifies the windows to search,
     and has the same meaning as in `next-window'.

 -- Function: get-window-with-predicate predicate &optional minibuf
          all-frames default
     This function calls the function PREDICATE for each of the windows
     in the cyclic order of windows in turn, passing it the window as
     an argument.  If the predicate returns non-`nil' for any window,
     this function stops and returns that window.  If no such window is
     found, the return value is DEFAULT (which defaults to `nil').

     The optional arguments MINIBUF and ALL-FRAMES specify the windows
     to search, and have the same meanings as in `next-window'.


File: elisp,  Node: Buffers and Windows,  Next: Switching Buffers,  Prev: Cyclic Window Ordering,  Up: Windows

28.9 Buffers and Windows
========================

This section describes low-level functions for examining and setting
the contents of windows.  *Note Switching Buffers::, for higher-level
functions for displaying a specific buffer in a window.

 -- Function: window-buffer &optional window
     This function returns the buffer that WINDOW is displaying.  If
     WINDOW is omitted or `nil' it defaults to the selected window.  If
     WINDOW is an internal window, this function returns `nil'.

 -- Function: set-window-buffer window buffer-or-name &optional
          keep-margins
     This function makes WINDOW display BUFFER-OR-NAME.  WINDOW should
     be a live window; if `nil', it defaults to the selected window.
     BUFFER-OR-NAME should be a buffer, or the name of an existing
     buffer.  This function does not change which window is selected,
     nor does it directly change which buffer is current (*note Current
     Buffer::).  Its return value is `nil'.

     If WINDOW is "strongly dedicated" to a buffer and BUFFER-OR-NAME
     does not specify that buffer, this function signals an error.
     *Note Dedicated Windows::.

     By default, this function resets WINDOW's position, display
     margins, fringe widths, and scroll bar settings, based on the local
     variables in the specified buffer.  However, if the optional
     argument KEEP-MARGINS is non-`nil', it leaves the display margins
     and fringe widths unchanged.

     When writing an application, you should normally use the
     higher-level functions described in *note Switching Buffers::,
     instead of calling `set-window-buffer' directly.

     This runs `window-scroll-functions', followed by
     `window-configuration-change-hook'.  *Note Window Hooks::.

 -- Variable: buffer-display-count
     This buffer-local variable records the number of times a buffer
     has been displayed in a window.  It is incremented each time
     `set-window-buffer' is called for the buffer.

 -- Variable: buffer-display-time
     This buffer-local variable records the time at which a buffer was
     last displayed in a window.  The value is `nil' if the buffer has
     never been displayed.  It is updated each time `set-window-buffer'
     is called for the buffer, with the value returned by
     `current-time' (*note Time of Day::).

 -- Function: get-buffer-window &optional buffer-or-name all-frames
     This function returns the first window displaying BUFFER-OR-NAME
     in the cyclic ordering of windows, starting from the selected
     window (*note Cyclic Window Ordering::).  If no such window
     exists, the return value is `nil'.

     BUFFER-OR-NAME should be a buffer or the name of a buffer; if
     omitted or `nil', it defaults to the current buffer.  The optional
     argument ALL-FRAMES specifies which windows to consider:

        * `t' means consider windows on all existing frames.

        * `visible' means consider windows on all visible frames.

        * 0 means consider windows on all visible or iconified frames.

        * A frame means consider windows on that frame only.

        * Any other value means consider windows on the selected frame.

     Note that these meanings differ slightly from those of the
     ALL-FRAMES argument to `next-window' (*note Cyclic Window
     Ordering::).  This function may be changed in a future version of
     Emacs to eliminate this discrepancy.

 -- Function: get-buffer-window-list &optional buffer-or-name minibuf
          all-frames
     This function returns a list of all windows currently displaying
     BUFFER-OR-NAME.  BUFFER-OR-NAME should be a buffer or the name of
     an existing buffer.  If omitted or `nil', it defaults to the
     current buffer.

     The arguments MINIBUF and ALL-FRAMES have the same meanings as in
     the function `next-window' (*note Cyclic Window Ordering::).  Note
     that the ALL-FRAMES argument does _not_ behave exactly like in
     `get-buffer-window'.

 -- Command: replace-buffer-in-windows &optional buffer-or-name
     This command replaces BUFFER-OR-NAME with some other buffer, in
     all windows displaying it.  BUFFER-OR-NAME should be a buffer, or
     the name of an existing buffer; if omitted or `nil', it defaults
     to the current buffer.

     The replacement buffer in each window is chosen via
     `switch-to-prev-buffer' (*note Window History::).  Any dedicated
     window displaying BUFFER-OR-NAME is deleted (*note Dedicated
     Windows::), unless it is the only window on its frame--if it is the
     only window, and that frame is not the only frame on its terminal,
     the frame is "dismissed" by calling the function specified by
     `frame-auto-hide-function' (*note Quitting Windows::).  If the
     dedicated window is the only window on the only frame on its
     terminal, the buffer is replaced anyway.


File: elisp,  Node: Switching Buffers,  Next: Choosing Window,  Prev: Buffers and Windows,  Up: Windows

28.10 Switching to a Buffer in a Window
=======================================

This section describes high-level functions for switching to a
specified buffer in some window.

   Do _not_ use these functions to make a buffer temporarily current
just so a Lisp program can access or modify it.  They have
side-effects, such as changing window histories (*note Window
History::), which will surprise the user if used that way.  If you want
to make a buffer current to modify it in Lisp, use
`with-current-buffer', `save-current-buffer', or `set-buffer'.  *Note
Current Buffer::.

 -- Command: switch-to-buffer buffer-or-name &optional norecord
          force-same-window
     This function displays BUFFER-OR-NAME in the selected window, and
     makes it the current buffer.  (In contrast, `set-buffer' makes the
     buffer current but does not display it; *note Current Buffer::).
     It is often used interactively (as the binding of `C-x b'), as
     well as in Lisp programs.  The return value is the buffer switched
     to.

     If BUFFER-OR-NAME is `nil', it defaults to the buffer returned by
     `other-buffer' (*note The Buffer List::).  If BUFFER-OR-NAME is a
     string that is not the name of any existing buffer, this function
     creates a new buffer with that name; the new buffer's major mode
     is determined by the variable `major-mode' (*note Major Modes::).

     Normally the specified buffer is put at the front of the buffer
     list--both the global buffer list and the selected frame's buffer
     list (*note The Buffer List::).  However, this is not done if the
     optional argument NORECORD is non-`nil'.

     If this function is unable to display the buffer in the selected
     window--usually because the selected window is a minibuffer window
     or is strongly dedicated to its buffer (*note Dedicated
     Windows::)--then it normally tries to display the buffer in some
     other window, in the manner of `pop-to-buffer' (see below).
     However, if the optional argument FORCE-SAME-WINDOW is non-`nil',
     it signals an error instead.

   The next two functions are similar to `switch-to-buffer', except for
the described features.

 -- Command: switch-to-buffer-other-window buffer-or-name &optional
          norecord
     This function makes the buffer specified by BUFFER-OR-NAME current
     and displays it in some window other than the selected window.  It
     uses the function `pop-to-buffer' internally (see below).

     If the selected window already displays the specified buffer, it
     continues to do so, but another window is nonetheless found to
     display it as well.

     The BUFFER-OR-NAME and NORECORD arguments have the same meanings
     as in `switch-to-buffer'.

 -- Command: switch-to-buffer-other-frame buffer-or-name &optional
          norecord
     This function makes the buffer specified by BUFFER-OR-NAME current
     and displays it, usually in a new frame.  It uses the function
     `pop-to-buffer' (see below).

     If the specified buffer is already displayed in another window, in
     any frame on the current terminal, this switches to that window
     instead of creating a new frame.  However, the selected window is
     never used for this.

     The BUFFER-OR-NAME and NORECORD arguments have the same meanings
     as in `switch-to-buffer'.

   The above commands use the function `pop-to-buffer', which flexibly
displays a buffer in some window and selects that window for editing.
In turn, `pop-to-buffer' uses `display-buffer' for displaying the
buffer.  Hence, all the variables affecting `display-buffer' will
affect it as well.  *Note Choosing Window::, for the documentation of
`display-buffer'.

 -- Command: pop-to-buffer buffer-or-name &optional action norecord
     This function makes BUFFER-OR-NAME the current buffer and displays
     it in some window, preferably not the window previously selected.
     It then selects the displaying window.  If that window is on a
     different graphical frame, that frame is given input focus if
     possible (*note Input Focus::).  The return value is the buffer
     that was switched to.

     If BUFFER-OR-NAME is `nil', it defaults to the buffer returned by
     `other-buffer' (*note The Buffer List::).  If BUFFER-OR-NAME is a
     string that is not the name of any existing buffer, this function
     creates a new buffer with that name; the new buffer's major mode
     is determined by the variable `major-mode' (*note Major Modes::).

     If ACTION is non-`nil', it should be a display action to pass to
     `display-buffer' (*note Choosing Window::).  Alternatively, a
     non-`nil', non-list value means to pop to a window other than the
     selected one--even if the buffer is already displayed in the
     selected window.

     Like `switch-to-buffer', this function updates the buffer list
     unless NORECORD is non-`nil'.


File: elisp,  Node: Choosing Window,  Next: Display Action Functions,  Prev: Switching Buffers,  Up: Windows

28.11 Choosing a Window for Display
===================================

The command `display-buffer' flexibly chooses a window for display, and
displays a specified buffer in that window.  It can be called
interactively, via the key binding `C-x 4 C-o'.  It is also used as a
subroutine by many functions and commands, including `switch-to-buffer'
and `pop-to-buffer' (*note Switching Buffers::).

   This command performs several complex steps to find a window to
display in.  These steps are described by means of "display actions",
which have the form `(FUNCTION . ALIST)'.  Here, FUNCTION is either a
function or a list of functions, which we refer to as "action
functions"; ALIST is an association list, which we refer to as "action
alists".

   An action function accepts two arguments: the buffer to display and
an action alist.  It attempts to display the buffer in some window,
picking or creating a window according to its own criteria.  If
successful, it returns the window; otherwise, it returns `nil'.  *Note
Display Action Functions::, for a list of predefined action functions.

   `display-buffer' works by combining display actions from several
sources, and calling the action functions in turn, until one of them
manages to display the buffer and returns a non-`nil' value.

 -- Command: display-buffer buffer-or-name &optional action frame
     This command makes BUFFER-OR-NAME appear in some window, without
     selecting the window or making the buffer current.  The argument
     BUFFER-OR-NAME must be a buffer or the name of an existing buffer.
     The return value is the window chosen to display the buffer.

     The optional argument ACTION, if non-`nil', should normally be a
     display action (described above).  `display-buffer' builds a list
     of action functions and an action alist, by consolidating display
     actions from the following sources (in order):

        * The variable `display-buffer-overriding-action'.

        * The user option `display-buffer-alist'.

        * A special action for handling `special-display-buffer-names'
          and `special-display-regexps', if either of those variables is
          non-`nil'.  *Note Choosing Window Options::.

        * The ACTION argument.

        * The user option `display-buffer-base-action'.

        * The constant `display-buffer-fallback-action'.

     Each action function is called in turn, passing the buffer as the
     first argument and the combined action alist as the second
     argument, until one of the functions returns non-`nil'.

     The argument ACTION can also have a non-`nil', non-list value.
     This has the special meaning that the buffer should be displayed
     in a window other than the selected one, even if the selected
     window is already displaying it.  If called interactively with a
     prefix argument, ACTION is `t'.

     The optional argument FRAME, if non-`nil', specifies which frames
     to check when deciding whether the buffer is already displayed.
     It is equivalent to adding an element `(reusable-frames . FRAME)'
     to the action alist of ACTION.  *Note Display Action Functions::.

 -- Variable: display-buffer-overriding-action
     The value of this variable should be a display action, which is
     treated with the highest priority by `display-buffer'.  The
     default value is empty, i.e. `(nil . nil)'.

 -- User Option: display-buffer-alist
     The value of this option is an alist mapping regular expressions to
     display actions.  If the name of the buffer passed to
     `display-buffer' matches a regular expression in this alist, then
     `display-buffer' uses the corresponding display action.

 -- User Option: display-buffer-base-action
     The value of this option should be a display action.  This option
     can be used to define a "standard" display action for calls to
     `display-buffer'.

 -- Constant: display-buffer-fallback-action
     This display action specifies the fallback behavior for
     `display-buffer' if no other display actions are given.


File: elisp,  Node: Display Action Functions,  Next: Choosing Window Options,  Prev: Choosing Window,  Up: Windows

28.12 Action Functions for `display-buffer'
===========================================

The following basic action functions are defined in Emacs.  Each of
these functions takes two arguments: BUFFER, the buffer to display, and
ALIST, an action alist.  Each action function returns the window if it
succeeds, and `nil' if it fails.

 -- Function: display-buffer-same-window buffer alist
     This function tries to display BUFFER in the selected window.  It
     fails if the selected window is a minibuffer window or is dedicated
     to another buffer (*note Dedicated Windows::).  It also fails if
     ALIST has a non-`nil' `inhibit-same-window' entry.

 -- Function: display-buffer-reuse-window buffer alist
     This function tries to "display" BUFFER by finding a window that
     is already displaying it.

     If ALIST has a non-`nil' `inhibit-same-window' entry, the selected
     window is not eligible for reuse.  If ALIST contains a
     `reusable-frames' entry, its value determines which frames to
     search for a reusable window:

        * `nil' means consider windows on the selected frame.
          (Actually, the last non-minibuffer frame.)

        * `t' means consider windows on all frames.

        * `visible' means consider windows on all visible frames.

        * 0 means consider windows on all visible or iconified frames.

        * A frame means consider windows on that frame only.

     If ALIST contains no `reusable-frames' entry, this function
     normally searches just the selected frame; however, if either the
     variable `display-buffer-reuse-frames' or the variable
     `pop-up-frames' is non-`nil', it searches all frames on the
     current terminal.  *Note Choosing Window Options::.

     If this function chooses a window on another frame, it makes that
     frame visible and raises it if necessary.

 -- Function: display-buffer-pop-up-frame buffer alist
     This function creates a new frame, and displays the buffer in that
     frame's window.  It actually performs the frame creation by calling
     the function specified in `pop-up-frame-function' (*note Choosing
     Window Options::).

 -- Function: display-buffer-pop-up-window buffer alist
     This function tries to display BUFFER by splitting the largest or
     least recently-used window (typically one on the selected frame).
     It actually performs the split by calling the function specified in
     `split-window-preferred-function' (*note Choosing Window
     Options::).

     It can fail if no window splitting can be performed for some reason
     (e.g. if there is just one frame and it has an `unsplittable'
     frame parameter; *note Buffer Parameters::).

 -- Function: display-buffer-use-some-window buffer alist
     This function tries to display BUFFER by choosing an existing
     window and displaying the buffer in that window.  It can fail if
     all windows are dedicated to another buffer (*note Dedicated
     Windows::).


File: elisp,  Node: Choosing Window Options,  Next: Window History,  Prev: Display Action Functions,  Up: Windows

28.13 Additional Options for Displaying Buffers
===============================================

The behavior of the standard display actions of `display-buffer' (*note
Choosing Window::) can be modified by a variety of user options.

 -- User Option: display-buffer-reuse-frames
     If the value of this variable is non-`nil', `display-buffer' may
     search all frames on the current terminal when looking for a
     window already displaying the specified buffer.  The default is
     `nil'.  This variable is consulted by the action function
     `display-buffer-reuse-window' (*note Display Action Functions::).

 -- User Option: pop-up-windows
     If the value of this variable is non-`nil', `display-buffer' is
     allowed to split an existing window to make a new window for
     displaying in.  This is the default.

     This variable is provided mainly for backward compatibility.  It is
     obeyed by `display-buffer' via a special mechanism in
     `display-buffer-fallback-action', which only calls the action
     function `display-buffer-pop-up-window' (*note Display Action
     Functions::) when the value is `nil'.  It is not consulted by
     `display-buffer-pop-up-window' itself, which the user may specify
     directly in `display-buffer-alist' etc.

 -- User Option: split-window-preferred-function
     This variable specifies a function for splitting a window, in
     order to make a new window for displaying a buffer.  It is used by
     the `display-buffer-pop-up-window' action function to actually
     split the window (*note Display Action Functions::).

     The default value is `split-window-sensibly', which is documented
     below.  The value must be a function that takes one argument, a
     window, and return either a new window (which is used to display
     the desired buffer) or `nil' (which means the splitting failed).

 -- Function: split-window-sensibly window
     This function tries to split WINDOW, and return the newly created
     window.  If WINDOW cannot be split, it returns `nil'.

     This function obeys the usual rules that determine when a window
     may be split (*note Splitting Windows::).  It first tries to split
     by placing the new window below, subject to the restriction
     imposed by `split-height-threshold' (see below), in addition to
     any other restrictions.  If that fails, it tries to split by
     placing the new window to the right, subject to
     `split-width-threshold' (see below).  If that fails, and the
     window is the only window on its frame, this function again tries
     to split and place the new window below, disregarding
     `split-height-threshold'.  If this fails as well, this function
     gives up and returns `nil'.

 -- User Option: split-height-threshold
     This variable, used by `split-window-sensibly', specifies whether
     to split the window placing the new window below.  If it is an
     integer, that means to split only if the original window has at
     least that many lines.  If it is `nil', that means not to split
     this way.

 -- User Option: split-width-threshold
     This variable, used by `split-window-sensibly', specifies whether
     to split the window placing the new window to the right.  If the
     value is an integer, that means to split only if the original
     window has at least that many columns.  If the value is `nil',
     that means not to split this way.

 -- User Option: pop-up-frames
     If the value of this variable is non-`nil', that means
     `display-buffer' may display buffers by making new frames.  The
     default is `nil'.

     A non-`nil' value also means that when `display-buffer' is looking
     for a window already displaying BUFFER-OR-NAME, it can search any
     visible or iconified frame, not just the selected frame.

     This variable is provided mainly for backward compatibility.  It is
     obeyed by `display-buffer' via a special mechanism in
     `display-buffer-fallback-action', which calls the action function
     `display-buffer-pop-up-frame' (*note Display Action Functions::)
     if the value is non-`nil'.  (This is done before attempting to
     split a window.)  This variable is not consulted by
     `display-buffer-pop-up-frame' itself, which the user may specify
     directly in `display-buffer-alist' etc.

 -- User Option: pop-up-frame-function
     This variable specifies a function for creating a new frame, in
     order to make a new window for displaying a buffer.  It is used by
     the `display-buffer-pop-up-frame' action function (*note Display
     Action Functions::).

     The value should be a function that takes no arguments and returns
     a frame, or `nil' if no frame could be created.  The default value
     is a function that creates a frame using the parameters specified
     by `pop-up-frame-alist' (see below).

 -- User Option: pop-up-frame-alist
     This variable holds an alist of frame parameters (*note Frame
     Parameters::), which is used by the default function in
     `pop-up-frame-function' to make a new frame.  The default is `nil'.

 -- User Option: special-display-buffer-names
     A list of buffer names identifying buffers that should be displayed
     specially.  If the name of BUFFER-OR-NAME is in this list,
     `display-buffer' handles the buffer specially.  By default, special
     display means to give the buffer a dedicated frame.

     If an element is a list, instead of a string, then the CAR of that
     list is the buffer name, and the rest of that list says how to
     create the frame.  There are two possibilities for the rest of
     that list (its CDR): It can be an alist, specifying frame
     parameters, or it can contain a function and arguments to give to
     it.  (The function's first argument is always the buffer to be
     displayed; the arguments from the list come after that.)

     For example:

          (("myfile" (minibuffer) (menu-bar-lines . 0)))

     specifies to display a buffer named `myfile' in a dedicated frame
     with specified `minibuffer' and `menu-bar-lines' parameters.

     The list of frame parameters can also use the phony frame
     parameters `same-frame' and `same-window'.  If the specified frame
     parameters include `(same-window . VALUE)' and VALUE is non-`nil',
     that means to display the buffer in the current selected window.
     Otherwise, if they include `(same-frame .  VALUE)' and VALUE is
     non-`nil', that means to display the buffer in a new window in the
     currently selected frame.

 -- User Option: special-display-regexps
     A list of regular expressions specifying buffers that should be
     displayed specially.  If the buffer's name matches any of the
     regular expressions in this list, `display-buffer' handles the
     buffer specially.  By default, special display means to give the
     buffer a dedicated frame.

     If an element is a list, instead of a string, then the CAR of the
     list is the regular expression, and the rest of the list says how
     to create the frame.  See `special-display-buffer-names' above.

 -- Function: special-display-p buffer-name
     This function returns non-`nil' if displaying a buffer named
     BUFFER-NAME with `display-buffer' would create a special frame.
     The value is `t' if it would use the default frame parameters, or
     else the specified list of frame parameters.

 -- User Option: special-display-function
     This variable holds the function to call to display a buffer
     specially.  It receives the buffer as an argument, and should
     return the window in which it is displayed.  The default value of
     this variable is `special-display-popup-frame', see below.

 -- Function: special-display-popup-frame buffer &optional args
     This function tries to make BUFFER visible in a frame of its own.
     If BUFFER is already displayed in some window, it makes that
     window's frame visible and raises it.  Otherwise, it creates a
     frame that is dedicated to BUFFER.  The return value is the window
     used to display BUFFER.

     If ARGS is an alist, it specifies frame parameters for the new
     frame.  If ARGS is a list whose CAR is a symbol, then `(car ARGS)'
     is a function to actually create and set up the frame; it is
     called with BUFFER as first argument, and `(cdr ARGS)' as
     additional arguments.

     This function always uses an existing window displaying BUFFER,
     whether or not it is in a frame of its own; but if you set up the
     above variables in your init file, before BUFFER was created, then
     presumably the window was previously made by this function.

 -- User Option: special-display-frame-alist
     This variable holds frame parameters for
     `special-display-popup-frame' to use when it creates a frame.

 -- User Option: same-window-buffer-names
     A list of buffer names for buffers that should be displayed in the
     selected window.  If a buffer's name is in this list,
     `display-buffer' handles the buffer by switching to it in the
     selected window.

 -- User Option: same-window-regexps
     A list of regular expressions that specify buffers that should be
     displayed in the selected window.  If the buffer's name matches
     any of the regular expressions in this list, `display-buffer'
     handles the buffer by switching to it in the selected window.

 -- Function: same-window-p buffer-name
     This function returns `t' if displaying a buffer named BUFFER-NAME
     with `display-buffer' would put it in the selected window.

 -- User Option: display-buffer-function
     This variable is the most flexible way to customize the behavior of
     `display-buffer'.  If it is non-`nil', it should be a function
     that `display-buffer' calls to do the work.  The function should
     accept two arguments, the first two arguments that `display-buffer'
     received.  It should choose or create a window, display the
     specified buffer in it, and then return the window.

     This variable takes precedence over all the other options described
     above.


File: elisp,  Node: Window History,  Next: Dedicated Windows,  Prev: Choosing Window Options,  Up: Windows

28.14 Window History
====================

Each window remembers the buffers it has previously displayed, and the
order in which these buffers were removed from it.  This history is
used, for example, by `replace-buffer-in-windows' (*note Buffers and
Windows::).  This list is automatically maintained by Emacs, but you can
use the following functions to explicitly inspect or alter it:

 -- Function: window-prev-buffers &optional window
     This function returns a list specifying the previous contents of
     WINDOW, which should be a live window and defaults to the selected
     window.

     Each list element has the form `(BUFFER WINDOW-START WINDOW-POS)',
     where BUFFER is a buffer previously shown in the window,
     WINDOW-START is the window start position when that buffer was
     last shown, and WINDOW-POS is the point position when that buffer
     was last shown.

     The list is ordered so that earlier elements correspond to more
     recently-shown buffers, and the first element usually corresponds
     to the buffer most recently removed from the window.

 -- Function: set-window-prev-buffers window prev-buffers
     This function sets WINDOW's previous buffers to the value of
     PREV-BUFFERS.  The argument WINDOW must be a live window and
     defaults to the selected one.  The argument PREV-BUFFERS should be
     a list of the same form as that returned by `window-prev-buffers'.

   In addition, each buffer maintains a list of "next buffers", which
is a list of buffers re-shown by `switch-to-prev-buffer' (see below).
This list is mainly used by `switch-to-prev-buffer' and
`switch-to-next-buffer' for choosing buffers to switch to.

 -- Function: window-next-buffers &optional window
     This function returns the list of buffers recently re-shown in
     WINDOW via `switch-to-prev-buffer'.  The WINDOW argument must
     denote a live window or `nil' (meaning the selected window).

 -- Function: set-window-next-buffers window next-buffers
     This function sets the next buffer list of WINDOW to NEXT-BUFFERS.
     The WINDOW argument should be a live window or `nil' (meaning the
     selected window).  The argument NEXT-BUFFERS should be a list of
     buffers.

   The following commands can be used to cycle through the global buffer
list, much like `bury-buffer' and `unbury-buffer'.  However, they cycle
according to the specified window's history list, rather than the
global buffer list.  In addition, they restore window-specific window
start and point positions, and may show a buffer even if it is already
shown in another window.  The `switch-to-prev-buffer' command, in
particular, is used by `replace-buffer-in-windows', `bury-buffer' and
`quit-window' to find a replacement buffer for a window.

 -- Command: switch-to-prev-buffer &optional window bury-or-kill
     This command displays the previous buffer in WINDOW.  The argument
     WINDOW should be a live window or `nil' (meaning the selected
     window).  If the optional argument BURY-OR-KILL is non-`nil', this
     means that the buffer currently shown in WINDOW is about to be
     buried or killed and consequently should not be switched to in
     future invocations of this command.

     The previous buffer is usually the buffer shown before the buffer
     currently shown in WINDOW.  However, a buffer that has been buried
     or killed, or has been already shown by a recent invocation of
     `switch-to-prev-buffer', does not qualify as previous buffer.

     If repeated invocations of this command have already shown all
     buffers previously shown in WINDOW, further invocations will show
     buffers from the buffer list of the frame WINDOW appears on (*note
     The Buffer List::), trying to skip buffers that are already shown
     in another window on that frame.

 -- Command: switch-to-next-buffer &optional window
     This command switches to the next buffer in WINDOW, thus undoing
     the effect of the last `switch-to-prev-buffer' command in WINDOW.
     The argument WINDOW must be a live window and defaults to the
     selected one.

     If there is no recent invocation of `switch-to-prev-buffer' that
     can be undone, this function tries to show a buffer from the
     buffer list of the frame WINDOW appears on (*note The Buffer
     List::).

   By default `switch-to-prev-buffer' and `switch-to-next-buffer' can
switch to a buffer that is already shown in another window on the same
frame.  The following option can be used to override this behavior.

 -- User Option: switch-to-visible-buffer
     If this variable is non-`nil', `switch-to-prev-buffer' and
     `switch-to-next-buffer' may switch to a buffer that is already
     visible on the same frame, provided the buffer was shown in the
     relevant window before.  If it is `nil', `switch-to-prev-buffer'
     and `switch-to-next-buffer' always try to avoid switching to a
     buffer that is already visible in another window on the same frame.


File: elisp,  Node: Dedicated Windows,  Next: Quitting Windows,  Prev: Window History,  Up: Windows

28.15 Dedicated Windows
=======================

Functions for displaying a buffer can be told to not use specific
windows by marking these windows as "dedicated" to their buffers.
`display-buffer' (*note Choosing Window::) never uses a dedicated
window for displaying another buffer in it.  `get-lru-window' and
`get-largest-window' (*note Selecting Windows::) do not consider
dedicated windows as candidates when their DEDICATED argument is
non-`nil'.  The behavior of `set-window-buffer' (*note Buffers and
Windows::) with respect to dedicated windows is slightly different, see
below.

   When `delete-windows-on' (*note Deleting Windows::) wants to delete
a dedicated window and that window is the only window on its frame, it
deletes the window's frame too, provided there are other frames left.
`replace-buffer-in-windows' (*note Switching Buffers::) tries to delete
all dedicated windows showing its buffer argument.  When such a window
is the only window on its frame, that frame is deleted, provided there
are other frames left.  If there are no more frames left, some other
buffer is displayed in the window, and the window is marked as
non-dedicated.

   When you kill a buffer (*note Killing Buffers::) displayed in a
dedicated window, any such window usually gets deleted too, since
`kill-buffer' calls `replace-buffer-in-windows' for cleaning up
windows.  Burying a buffer (*note The Buffer List::) deletes the
selected window if it is dedicated to that buffer.  If, however, that
window is the only window on its frame, `bury-buffer' displays another
buffer in it and iconifies the frame.

 -- Function: window-dedicated-p &optional window
     This function returns non-`nil' if WINDOW is dedicated to its
     buffer and `nil' otherwise.  More precisely, the return value is
     the value assigned by the last call of `set-window-dedicated-p' for
     WINDOW, or `nil' if that function was never called with WINDOW as
     its argument.  The default for WINDOW is the selected window.

 -- Function: set-window-dedicated-p window flag
     This function marks WINDOW as dedicated to its buffer if FLAG is
     non-`nil', and non-dedicated otherwise.

     As a special case, if FLAG is `t', WINDOW becomes "strongly"
     dedicated to its buffer.  `set-window-buffer' signals an error
     when the window it acts upon is strongly dedicated to its buffer
     and does not already display the buffer it is asked to display.
     Other functions do not treat `t' differently from any non-`nil'
     value.


File: elisp,  Node: Quitting Windows,  Next: Window Point,  Prev: Dedicated Windows,  Up: Windows

28.16 Quitting Windows
======================

When you want to get rid of a window used for displaying a buffer, you
can call `delete-window' or `delete-windows-on' (*note Deleting
Windows::) to remove that window from its frame.  If the buffer is
shown on a separate frame, you might want to call `delete-frame' (*note
Deleting Frames::) instead.  If, on the other hand, a window has been
reused for displaying the buffer, you might prefer showing the buffer
previously shown in that window, by calling the function
`switch-to-prev-buffer' (*note Window History::).  Finally, you might
want to either bury (*note The Buffer List::) or kill (*note Killing
Buffers::) the window's buffer.

   The following function uses information on how the window for
displaying the buffer was obtained in the first place, thus attempting
to automate the above decisions for you.

 -- Command: quit-window &optional kill window
     This command quits WINDOW and buries its buffer.  The argument
     WINDOW must be a live window and defaults to the selected one.
     With prefix argument KILL non-`nil', it kills the buffer instead
     of burying it.

     Quitting WINDOW means to proceed as follows: If WINDOW was created
     specially for displaying its current buffer, delete WINDOW
     provided its frame contains at least one other live window.  If
     WINDOW is the only window on its frame and there are other frames
     on the frame's terminal, the value of KILL determines how to
     proceed with the window.  If KILL is `nil', the fate of the frame
     is determined by calling `frame-auto-hide-function' (see below)
     with that frame as sole argument.  If KILL is non-`nil', the frame
     is deleted unconditionally.

     If WINDOW was reused for displaying its buffer, this command tries
     to display the buffer previously shown in it.  It also tries to
     restore the window start (*note Window Start and End::) and point
     (*note Window Point::) positions of the previously shown buffer.
     If, in addition, the current buffer was temporarily resized, this
     command will also try to restore the original height of WINDOW.

     The three cases described so far require that the buffer shown in
     WINDOW is still the buffer displayed by the last buffer display
     function for this window.  If another buffer has been shown in the
     meantime, or the buffer previously shown no longer exists, this
     command calls `switch-to-prev-buffer' (*note Window History::) to
     show some other buffer instead.

   The function `quit-window' bases its decisions on information stored
in WINDOW's `quit-restore' window parameter (*note Window
Parameters::), and resets that parameter to `nil' after it's done.

   The following option specifies how to deal with a frame containing
just one window that should be either quit, or whose buffer should be
buried.

 -- User Option: frame-auto-hide-function
     The function specified by this option is called to automatically
     hide frames.  This function is called with one argument--a frame.

     The function specified here is called by `bury-buffer' (*note The
     Buffer List::) when the selected window is dedicated and shows the
     buffer that should be buried.  It is also called by `quit-window'
     (see above) when the frame of the window that should be quit has
     been specially created for displaying that window's buffer and the
     buffer should be buried.

     The default is to call `iconify-frame' (*note Visibility of
     Frames::).  Alternatively, you may specify either `delete-frame'
     (*note Deleting Frames::) to remove the frame from its display,
     `ignore' to leave the frame unchanged, or any other function that
     can take a frame as its sole argument.

     Note that the function specified by this option is called if and
     only if there is at least one other frame on the terminal of the
     frame it's supposed to handle, and that frame contains only one
     live window.


File: elisp,  Node: Window Point,  Next: Window Start and End,  Prev: Quitting Windows,  Up: Windows

28.17 Windows and Point
=======================

Each window has its own value of point (*note Point::), independent of
the value of point in other windows displaying the same buffer.  This
makes it useful to have multiple windows showing one buffer.

   * The window point is established when a window is first created; it
     is initialized from the buffer's point, or from the window point
     of another window opened on the buffer if such a window exists.

   * Selecting a window sets the value of point in its buffer from the
     window's value of point.  Conversely, deselecting a window sets the
     window's value of point from that of the buffer.  Thus, when you
     switch between windows that display a given buffer, the point
     value for the selected window is in effect in the buffer, while
     the point values for the other windows are stored in those windows.

   * As long as the selected window displays the current buffer, the
     window's point and the buffer's point always move together; they
     remain equal.

   As far as the user is concerned, point is where the cursor is, and
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.

 -- Function: window-point &optional window
     This function returns the current position of point in WINDOW.
     For a nonselected window, this is the value point would have (in
     that window's buffer) if that window were selected.  The default
     for WINDOW is the selected window.

     When WINDOW is the selected window and its buffer is also the
     current buffer, the value returned is the same as point in that
     buffer.  Strictly speaking, it would be more correct to return the
     "top-level" value of point, outside of any `save-excursion' forms.
     But that value is hard to find.

 -- Function: set-window-point window position
     This function positions point in WINDOW at position POSITION in
     WINDOW's buffer.  It returns POSITION.

     If WINDOW is selected, and its buffer is current, this simply does
     `goto-char'.

 -- Variable: window-point-insertion-type
     This variable specifies the marker insertion type (*note Marker
     Insertion Types::) of `window-point'.  The default is `nil', so
     `window-point' will stay behind text inserted there.


File: elisp,  Node: Window Start and End,  Next: Textual Scrolling,  Prev: Window Point,  Up: Windows

28.18 The Window Start and End Positions
========================================

Each window maintains a marker used to keep track of a buffer position
that specifies where in the buffer display should start.  This position
is called the "display-start" position of the window (or just the
"start").  The character after this position is the one that appears at
the upper left corner of the window.  It is usually, but not
inevitably, at the beginning of a text line.

   After switching windows or buffers, and in some other cases, if the
window start is in the middle of a line, Emacs adjusts the window start
to the start of a line.  This prevents certain operations from leaving
the window start at a meaningless point within a line.  This feature
may interfere with testing some Lisp code by executing it using the
commands of Lisp mode, because they trigger this readjustment.  To test
such code, put it into a command and bind the command to a key.

 -- Function: window-start &optional window
     This function returns the display-start position of window WINDOW.
     If WINDOW is `nil', the selected window is used.

     When you create a window, or display a different buffer in it, the
     display-start position is set to a display-start position recently
     used for the same buffer, or to `point-min' if the buffer doesn't
     have any.

     Redisplay updates the window-start position (if you have not
     specified it explicitly since the previous redisplay)--to make
     sure point appears on the screen.  Nothing except redisplay
     automatically changes the window-start position; if you move
     point, do not expect the window-start position to change in
     response until after the next redisplay.

 -- Function: window-end &optional window update
     This function returns the position where display of its buffer
     ends in WINDOW.  The default for WINDOW is the selected window.

     Simply changing the buffer text or moving point does not update the
     value that `window-end' returns.  The value is updated only when
     Emacs redisplays and redisplay completes without being preempted.

     If the last redisplay of WINDOW was preempted, and did not finish,
     Emacs does not know the position of the end of display in that
     window.  In that case, this function returns `nil'.

     If UPDATE is non-`nil', `window-end' always returns an up-to-date
     value for where display ends, based on the current `window-start'
     value.  If a previously saved value of that position is still
     valid, `window-end' returns that value; otherwise it computes the
     correct value by scanning the buffer text.

     Even if UPDATE is non-`nil', `window-end' does not attempt to
     scroll the display if point has moved off the screen, the way real
     redisplay would do.  It does not alter the `window-start' value.
     In effect, it reports where the displayed text will end if
     scrolling is not required.

 -- Function: set-window-start window position &optional noforce
     This function sets the display-start position of WINDOW to
     POSITION in WINDOW's buffer.  It returns POSITION.

     The display routines insist that the position of point be visible
     when a buffer is displayed.  Normally, they change the
     display-start position (that is, scroll the window) whenever
     necessary to make point visible.  However, if you specify the
     start position with this function using `nil' for NOFORCE, it
     means you want display to start at POSITION even if that would put
     the location of point off the screen.  If this does place point
     off screen, the display routines move point to the left margin on
     the middle line in the window.

     For example, if point is 1 and you set the start of the window
     to 37, the start of the next line, point will be "above" the top
     of the window.  The display routines will automatically move point
     if it is still 1 when redisplay occurs.  Here is an example:

          ;; Here is what `foo' looks like before executing
          ;;   the `set-window-start' expression.

          ---------- Buffer: foo ----------
          -!-This is the contents of buffer foo.
          2
          3
          4
          5
          6
          ---------- Buffer: foo ----------

          (set-window-start
           (selected-window)
           (save-excursion
             (goto-char 1)
             (forward-line 1)
             (point)))
          => 37

          ;; Here is what `foo' looks like after executing
          ;;   the `set-window-start' expression.
          ---------- Buffer: foo ----------
          2
          3
          -!-4
          5
          6
          ---------- Buffer: foo ----------

     If NOFORCE is non-`nil', and POSITION would place point off screen
     at the next redisplay, then redisplay computes a new window-start
     position that works well with point, and thus POSITION is not used.

 -- Function: pos-visible-in-window-p &optional position window
          partially
     This function returns non-`nil' if POSITION is within the range of
     text currently visible on the screen in WINDOW.  It returns `nil'
     if POSITION is scrolled vertically out of view.  Locations that
     are partially obscured are not considered visible unless PARTIALLY
     is non-`nil'.  The argument POSITION defaults to the current
     position of point in WINDOW; WINDOW, to the selected window.  If
     POSITION is `t', that means to check the last visible position in
     WINDOW.

     This function considers only vertical scrolling.  If POSITION is
     out of view only because WINDOW has been scrolled horizontally,
     `pos-visible-in-window-p' returns non-`nil' anyway.  *Note
     Horizontal Scrolling::.

     If POSITION is visible, `pos-visible-in-window-p' returns `t' if
     PARTIALLY is `nil'; if PARTIALLY is non-`nil', and the character
     following POSITION is fully visible, it returns a list of the form
     `(X Y)', where X and Y are the pixel coordinates relative to the
     top left corner of the window; otherwise it returns an extended
     list of the form `(X Y RTOP RBOT ROWH VPOS)', where RTOP and RBOT
     specify the number of off-window pixels at the top and bottom of
     the row at POSITION, ROWH specifies the visible height of that
     row, and VPOS specifies the vertical position (zero-based row
     number) of that row.

     Here is an example:

          ;; If point is off the screen now, recenter it now.
          (or (pos-visible-in-window-p
               (point) (selected-window))
              (recenter 0))

 -- Function: window-line-height &optional line window
     This function returns the height of text line LINE in WINDOW.  If
     LINE is one of `header-line' or `mode-line', `window-line-height'
     returns information about the corresponding line of the window.
     Otherwise, LINE is a text line number starting from 0.  A negative
     number counts from the end of the window.  The default for LINE is
     the current line in WINDOW; the default for WINDOW is the selected
     window.

     If the display is not up to date, `window-line-height' returns
     `nil'.  In that case, `pos-visible-in-window-p' may be used to
     obtain related information.

     If there is no line corresponding to the specified LINE,
     `window-line-height' returns `nil'.  Otherwise, it returns a list
     `(HEIGHT VPOS YPOS OFFBOT)', where HEIGHT is the height in pixels
     of the visible part of the line, VPOS and YPOS are the vertical
     position in lines and pixels of the line relative to the top of
     the first text line, and OFFBOT is the number of off-window pixels
     at the bottom of the text line.  If there are off-window pixels at
     the top of the (first) text line, YPOS is negative.


File: elisp,  Node: Textual Scrolling,  Next: Vertical Scrolling,  Prev: Window Start and End,  Up: Windows

28.19 Textual Scrolling
=======================

"Textual scrolling" means moving the text up or down through a window.
It works by changing the window's display-start location.  It may also
change the value of `window-point' to keep point on the screen (*note
Window Point::).

   The basic textual scrolling functions are `scroll-up' (which scrolls
forward) and `scroll-down' (which scrolls backward).  In these function
names, "up" and "down" refer to the direction of motion of the buffer
text relative to the window.  Imagine that the text is written on a
long roll of paper and that the scrolling commands move the paper up
and down.  Thus, if you are looking at the middle of a buffer and
repeatedly call `scroll-down', you will eventually see the beginning of
the buffer.

   Unfortunately, this sometimes causes confusion, because some people
tend to think in terms of the opposite convention: they imagine the
window moving over text that remains in place, so that "down" commands
take you to the end of the buffer.  This convention is consistent with
fact that such a command is bound to a key named <PageDown> on modern
keyboards.

   Textual scrolling functions (aside from `scroll-other-window') have
unpredictable results if the current buffer is not the one displayed in
the selected window.  *Note Current Buffer::.

   If the window contains a row taller than the height of the window
(for example in the presence of a large image), the scroll functions
will adjust the window's vertical scroll position to scroll the
partially visible row.  Lisp callers can disable this feature by
binding the variable `auto-window-vscroll' to `nil' (*note Vertical
Scrolling::).

 -- Command: scroll-up &optional count
     This function scrolls forward by COUNT lines in the selected
     window.

     If COUNT is negative, it scrolls backward instead.  If COUNT is
     `nil' (or omitted), the distance scrolled is
     `next-screen-context-lines' lines less than the height of the
     window's text area.

     If the selected window cannot be scrolled any further, this
     function signals an error.  Otherwise, it returns `nil'.

 -- Command: scroll-down &optional count
     This function scrolls backward by COUNT lines in the selected
     window.

     If COUNT is negative, it scrolls forward instead.  In other
     respects, it behaves the same way as `scroll-up' does.

 -- Command: scroll-up-command &optional count
     This behaves like `scroll-up', except that if the selected window
     cannot be scrolled any further and the value of the variable
     `scroll-error-top-bottom' is `t', it tries to move to the end of
     the buffer instead.  If point is already there, it signals an
     error.

 -- Command: scroll-down-command &optional count
     This behaves like `scroll-down', except that if the selected
     window cannot be scrolled any further and the value of the variable
     `scroll-error-top-bottom' is `t', it tries to move to the
     beginning of the buffer instead.  If point is already there, it
     signals an error.

 -- Command: scroll-other-window &optional count
     This function scrolls the text in another window upward COUNT
     lines.  Negative values of COUNT, or `nil', are handled as in
     `scroll-up'.

     You can specify which buffer to scroll by setting the variable
     `other-window-scroll-buffer' to a buffer.  If that buffer isn't
     already displayed, `scroll-other-window' displays it in some
     window.

     When the selected window is the minibuffer, the next window is
     normally the leftmost one immediately above it.  You can specify a
     different window to scroll, when the minibuffer is selected, by
     setting the variable `minibuffer-scroll-window'.  This variable
     has no effect when any other window is selected.  When it is
     non-`nil' and the minibuffer is selected, it takes precedence over
     `other-window-scroll-buffer'.  *Note Definition of
     minibuffer-scroll-window::.

     When the minibuffer is active, it is the next window if the
     selected window is the one at the bottom right corner.  In this
     case, `scroll-other-window' attempts to scroll the minibuffer.  If
     the minibuffer contains just one line, it has nowhere to scroll
     to, so the line reappears after the echo area momentarily displays
     the message `End of buffer'.

 -- Variable: other-window-scroll-buffer
     If this variable is non-`nil', it tells `scroll-other-window'
     which buffer's window to scroll.

 -- User Option: scroll-margin
     This option specifies the size of the scroll margin--a minimum
     number of lines between point and the top or bottom of a window.
     Whenever point gets within this many lines of the top or bottom of
     the window, redisplay scrolls the text automatically (if possible)
     to move point out of the margin, closer to the center of the
     window.

 -- User Option: scroll-conservatively
     This variable controls how scrolling is done automatically when
     point moves off the screen (or into the scroll margin).  If the
     value is a positive integer N, then redisplay scrolls the text up
     to N lines in either direction, if that will bring point back into
     proper view.  This behavior is called "conservative scrolling".
     Otherwise, scrolling happens in the usual way, under the control of
     other variables such as `scroll-up-aggressively' and
     `scroll-down-aggressively'.

     The default value is zero, which means that conservative scrolling
     never happens.

 -- User Option: scroll-down-aggressively
     The value of this variable should be either `nil' or a fraction F
     between 0 and 1.  If it is a fraction, that specifies where on the
     screen to put point when scrolling down.  More precisely, when a
     window scrolls down because point is above the window start, the
     new start position is chosen to put point F part of the window
     height from the top.  The larger F, the more aggressive the
     scrolling.

     A value of `nil' is equivalent to .5, since its effect is to center
     point.  This variable automatically becomes buffer-local when set
     in any fashion.

 -- User Option: scroll-up-aggressively
     Likewise, for scrolling up.  The value, F, specifies how far point
     should be placed from the bottom of the window; thus, as with
     `scroll-up-aggressively', a larger value scrolls more aggressively.

 -- User Option: scroll-step
     This variable is an older variant of `scroll-conservatively'.  The
     difference is that if its value is N, that permits scrolling only
     by precisely N lines, not a smaller number.  This feature does not
     work with `scroll-margin'.  The default value is zero.

 -- User Option: scroll-preserve-screen-position
     If this option is `t', whenever a scrolling command moves point
     off-window, Emacs tries to adjust point to keep the cursor at its
     old vertical position in the window, rather than the window edge.

     If the value is non-`nil' and not `t', Emacs adjusts point to keep
     the cursor at the same vertical position, even if the scrolling
     command didn't move point off-window.

     This option affects all scroll commands that have a non-`nil'
     `scroll-command' symbol property.

 -- User Option: next-screen-context-lines
     The value of this variable is the number of lines of continuity to
     retain when scrolling by full screens.  For example, `scroll-up'
     with an argument of `nil' scrolls so that this many lines at the
     bottom of the window appear instead at the top.  The default value
     is `2'.

 -- User Option: scroll-error-top-bottom
     If this option is `nil' (the default), `scroll-up-command' and
     `scroll-down-command' simply signal an error when no more
     scrolling is possible.

     If the value is `t', these commands instead move point to the
     beginning or end of the buffer (depending on scrolling direction);
     only if point is already on that position do they signal an error.

 -- Command: recenter &optional count
     This function scrolls the text in the selected window so that
     point is displayed at a specified vertical position within the
     window.  It does not "move point" with respect to the text.

     If COUNT is a non-negative number, that puts the line containing
     point COUNT lines down from the top of the window.  If COUNT is a
     negative number, then it counts upward from the bottom of the
     window, so that -1 stands for the last usable line in the window.

     If COUNT is `nil' (or a non-`nil' list), `recenter' puts the line
     containing point in the middle of the window.  If COUNT is `nil',
     this function may redraw the frame, according to the value of
     `recenter-redisplay'.

     When `recenter' is called interactively, COUNT is the raw prefix
     argument.  Thus, typing `C-u' as the prefix sets the COUNT to a
     non-`nil' list, while typing `C-u 4' sets COUNT to 4, which
     positions the current line four lines from the top.

     With an argument of zero, `recenter' positions the current line at
     the top of the window.  The command `recenter-top-bottom' offers a
     more convenient way to achieve this.

 -- User Option: recenter-redisplay
     If this variable is non-`nil', calling `recenter' with a `nil'
     argument redraws the frame.  The default value is `tty', which
     means only redraw the frame if it is a tty frame.

 -- Command: recenter-top-bottom &optional count
     This command, which is the default binding for `C-l', acts like
     `recenter', except if called with no argument.  In that case,
     successive calls place point according to the cycling order defined
     by the variable `recenter-positions'.

 -- User Option: recenter-positions
     This variable controls how `recenter-top-bottom' behaves when
     called with no argument.  The default value is `(middle top
     bottom)', which means that successive calls of
     `recenter-top-bottom' with no argument cycle between placing point
     at the middle, top, and bottom of the window.


File: elisp,  Node: Vertical Scrolling,  Next: Horizontal Scrolling,  Prev: Textual Scrolling,  Up: Windows

28.20 Vertical Fractional Scrolling
===================================

"Vertical fractional scrolling" means shifting text in a window up or
down by a specified multiple or fraction of a line.  Each window has a
"vertical scroll position", which is a number, never less than zero.
It specifies how far to raise the contents of the window.  Raising the
window contents generally makes all or part of some lines disappear off
the top, and all or part of some other lines appear at the bottom.  The
usual value is zero.

   The vertical scroll position is measured in units of the normal line
height, which is the height of the default font.  Thus, if the value is
.5, that means the window contents are scrolled up half the normal line
height.  If it is 3.3, that means the window contents are scrolled up
somewhat over three times the normal line height.

   What fraction of a line the vertical scrolling covers, or how many
lines, depends on what the lines contain.  A value of .5 could scroll a
line whose height is very short off the screen, while a value of 3.3
could scroll just part of the way through a tall line or an image.

 -- Function: window-vscroll &optional window pixels-p
     This function returns the current vertical scroll position of
     WINDOW.  The default for WINDOW is the selected window.  If
     PIXELS-P is non-`nil', the return value is measured in pixels,
     rather than in units of the normal line height.

          (window-vscroll)
               => 0

 -- Function: set-window-vscroll window lines &optional pixels-p
     This function sets WINDOW's vertical scroll position to LINES.  If
     WINDOW is `nil', the selected window is used.  The argument LINES
     should be zero or positive; if not, it is taken as zero.

     The actual vertical scroll position must always correspond to an
     integral number of pixels, so the value you specify is rounded
     accordingly.

     The return value is the result of this rounding.

          (set-window-vscroll (selected-window) 1.2)
               => 1.13

     If PIXELS-P is non-`nil', LINES specifies a number of pixels.  In
     this case, the return value is LINES.

 -- Variable: auto-window-vscroll
     If this variable is non-`nil', the line-move, scroll-up, and
     scroll-down functions will automatically modify the vertical scroll
     position to scroll through display rows that are taller than the
     height of the window, for example in the presence of large images.


File: elisp,  Node: Horizontal Scrolling,  Next: Coordinates and Windows,  Prev: Vertical Scrolling,  Up: Windows

28.21 Horizontal Scrolling
==========================

"Horizontal scrolling" means shifting the image in the window left or
right by a specified multiple of the normal character width.  Each
window has a "horizontal scroll position", which is a number, never
less than zero.  It specifies how far to shift the contents left.
Shifting the window contents left generally makes all or part of some
characters disappear off the left, and all or part of some other
characters appear at the right.  The usual value is zero.

   The horizontal scroll position is measured in units of the normal
character width, which is the width of space in the default font.  Thus,
if the value is 5, that means the window contents are scrolled left by 5
times the normal character width.  How many characters actually
disappear off to the left depends on their width, and could vary from
line to line.

   Because we read from side to side in the "inner loop", and from top
to bottom in the "outer loop", the effect of horizontal scrolling is
not like that of textual or vertical scrolling.  Textual scrolling
involves selection of a portion of text to display, and vertical
scrolling moves the window contents contiguously; but horizontal
scrolling causes part of _each line_ to go off screen.

   Usually, no horizontal scrolling is in effect; then the leftmost
column is at the left edge of the window.  In this state, scrolling to
the right is meaningless, since there is no data to the left of the edge
to be revealed by it; so this is not allowed.  Scrolling to the left is
allowed; it scrolls the first columns of text off the edge of the window
and can reveal additional columns on the right that were truncated
before.  Once a window has a nonzero amount of leftward horizontal
scrolling, you can scroll it back to the right, but only so far as to
reduce the net horizontal scroll to zero.  There is no limit to how far
left you can scroll, but eventually all the text will disappear off the
left edge.

   If `auto-hscroll-mode' is set, redisplay automatically alters the
horizontal scrolling of a window as necessary to ensure that point is
always visible.  However, you can still set the horizontal scrolling
value explicitly.  The value you specify serves as a lower bound for
automatic scrolling, i.e. automatic scrolling will not scroll a window
to a column less than the specified one.

 -- Command: scroll-left &optional count set-minimum
     This function scrolls the selected window COUNT columns to the
     left (or to the right if COUNT is negative).  The default for
     COUNT is the window width, minus 2.

     The return value is the total amount of leftward horizontal
     scrolling in effect after the change--just like the value returned
     by `window-hscroll' (below).

     Once you scroll a window as far right as it can go, back to its
     normal position where the total leftward scrolling is zero,
     attempts to scroll any farther right have no effect.

     If SET-MINIMUM is non-`nil', the new scroll amount becomes the
     lower bound for automatic scrolling; that is, automatic scrolling
     will not scroll a window to a column less than the value returned
     by this function.  Interactive calls pass non-`nil' for
     SET-MINIMUM.

 -- Command: scroll-right &optional count set-minimum
     This function scrolls the selected window COUNT columns to the
     right (or to the left if COUNT is negative).  The default for
     COUNT is the window width, minus 2.  Aside from the direction of
     scrolling, this works just like `scroll-left'.

 -- Function: window-hscroll &optional window
     This function returns the total leftward horizontal scrolling of
     WINDOW--the number of columns by which the text in WINDOW is
     scrolled left past the left margin.  The default for WINDOW is the
     selected window.

     The return value is never negative.  It is zero when no horizontal
     scrolling has been done in WINDOW (which is usually the case).

          (window-hscroll)
               => 0
          (scroll-left 5)
               => 5
          (window-hscroll)
               => 5

 -- Function: set-window-hscroll window columns
     This function sets horizontal scrolling of WINDOW.  The value of
     COLUMNS specifies the amount of scrolling, in terms of columns
     from the left margin.  The argument COLUMNS should be zero or
     positive; if not, it is taken as zero.  Fractional values of
     COLUMNS are not supported at present.

     Note that `set-window-hscroll' may appear not to work if you test
     it by evaluating a call with `M-:' in a simple way.  What happens
     is that the function sets the horizontal scroll value and returns,
     but then redisplay adjusts the horizontal scrolling to make point
     visible, and this overrides what the function did.  You can
     observe the function's effect if you call it while point is
     sufficiently far from the left margin that it will remain visible.

     The value returned is COLUMNS.

          (set-window-hscroll (selected-window) 10)
               => 10

   Here is how you can determine whether a given position POSITION is
off the screen due to horizontal scrolling:

     (defun hscroll-on-screen (window position)
       (save-excursion
         (goto-char position)
         (and
          (>= (- (current-column) (window-hscroll window)) 0)
          (< (- (current-column) (window-hscroll window))
             (window-width window)))))


File: elisp,  Node: Coordinates and Windows,  Next: Window Configurations,  Prev: Horizontal Scrolling,  Up: Windows

28.22 Coordinates and Windows
=============================

This section describes functions that report the position of a window.
Most of these functions report positions relative to the window's
frame.  In this case, the coordinate origin `(0,0)' lies near the upper
left corner of the frame.  For technical reasons, on graphical displays
the origin is not located at the exact corner of the graphical window
as it appears on the screen.  If Emacs is built with the GTK+ toolkit,
the origin is at the upper left corner of the frame area used for
displaying Emacs windows, below the title-bar, GTK+ menu bar, and tool
bar (since these are drawn by the window manager and/or GTK+, not by
Emacs).  But if Emacs is not built with GTK+, the origin is at the
upper left corner of the tool bar (since in this case Emacs itself
draws the tool bar).  In both cases, the X and Y coordinates increase
rightward and downward respectively.

   Except where noted, X and Y coordinates are reported in integer
character units, i.e. numbers of lines and columns respectively.  On a
graphical display, each "line" and "column" corresponds to the height
and width of a default character specified by the frame's default font.

 -- Function: window-edges &optional window
     This function returns a list of the edge coordinates of WINDOW.
     If WINDOW is omitted or `nil', it defaults to the selected window.

     The return value has the form `(LEFT TOP RIGHT BOTTOM)'.  These
     list elements are, respectively, the X coordinate of the leftmost
     column occupied by the window, the Y coordinate of the topmost
     row, the X coordinate one column to the right of the rightmost
     column, and the Y coordinate one row down from the bottommost row.

     Note that these are the actual outer edges of the window, including
     any header line, mode line, scroll bar, fringes, and display
     margins.  On a text terminal, if the window has a neighbor on its
     right, its right edge includes the separator line between the
     window and its neighbor.

 -- Function: window-inside-edges &optional window
     This function is similar to `window-edges', but the returned edge
     values are for the text area of the window.  They exclude any
     header line, mode line, scroll bar, fringes, display margins, and
     vertical separator.

 -- Function: window-top-line &optional window
     This function returns the Y coordinate of the topmost row of
     WINDOW, equivalent to the TOP entry in the list returned by
     `window-edges'.

 -- Function: window-left-column &optional window
     This function returns the X coordinate of the leftmost column of
     WINDOW, equivalent to the LEFT entry in the list returned by
     `window-edges'.

   The following functions can be used to relate a set of
frame-relative coordinates to a window:

 -- Function: window-at x y &optional frame
     This function returns the live window at the frame-relative
     coordinates X and Y, on frame FRAME.  If there is no window at
     that position, the return value is `nil'.  If FRAME is omitted or
     `nil', it defaults to the selected frame.

 -- Function: coordinates-in-window-p coordinates window
     This function checks whether a window WINDOW occupies the
     frame-relative coordinates COORDINATES, and if so, which part of
     the window that is.  WINDOW should be a live window.  COORDINATES
     should be a cons cell of the form `(X . Y)', where X and Y are
     frame-relative coordinates.

     If there is no window at the specified position, the return value
     is `nil' .  Otherwise, the return value is one of the following:

    `(RELX . RELY)'
          The coordinates are inside WINDOW.  The numbers RELX and RELY
          are the equivalent window-relative coordinates for the
          specified position, counting from 0 at the top left corner of
          the window.

    `mode-line'
          The coordinates are in the mode line of WINDOW.

    `header-line'
          The coordinates are in the header line of WINDOW.

    `vertical-line'
          The coordinates are in the vertical line between WINDOW and
          its neighbor to the right.  This value occurs only if the
          window doesn't have a scroll bar; positions in a scroll bar
          are considered outside the window for these purposes.

    `left-fringe'
    `right-fringe'
          The coordinates are in the left or right fringe of the window.

    `left-margin'
    `right-margin'
          The coordinates are in the left or right margin of the window.

    `nil'
          The coordinates are not in any part of WINDOW.

     The function `coordinates-in-window-p' does not require a frame as
     argument because it always uses the frame that WINDOW is on.

   The following functions return window positions in pixels, rather
than character units.  Though mostly useful on graphical displays, they
can also be called on text terminals, where the screen area of each
text character is taken to be "one pixel".

 -- Function: window-pixel-edges &optional window
     This function returns a list of pixel coordinates for the edges of
     WINDOW.  If WINDOW is omitted or `nil', it defaults to the
     selected window.

     The return value has the form `(LEFT TOP RIGHT BOTTOM)'.  The list
     elements are, respectively, the X pixel coordinate of the left
     window edge, the Y pixel coordinate of the top edge, one more than
     the X pixel coordinate of the right edge, and one more than the Y
     pixel coordinate of the bottom edge.

 -- Function: window-inside-pixel-edges &optional window
     This function is like `window-pixel-edges', except that it returns
     the pixel coordinates for the edges of the window's text area,
     rather than the pixel coordinates for the edges of the window
     itself.  WINDOW must specify a live window.

   The following functions return window positions in pixels, relative
to the display screen rather than the frame:

 -- Function: window-absolute-pixel-edges &optional window
     This function is like `window-pixel-edges', except that it returns
     the edge pixel coordinates relative to the top left corner of the
     display screen.

 -- Function: window-inside-absolute-pixel-edges &optional window
     This function is like `window-inside-pixel-edges', except that it
     returns the edge pixel coordinates relative to the top left corner
     of the display screen.  WINDOW must specify a live window.


File: elisp,  Node: Window Configurations,  Next: Window Parameters,  Prev: Coordinates and Windows,  Up: Windows

28.23 Window Configurations
===========================

A "window configuration" records the entire layout of one frame--all
windows, their sizes, which buffers they contain, how those buffers are
scrolled, and their values of point and the mark; also their fringes,
margins, and scroll bar settings.  It also includes the value of
`minibuffer-scroll-window'.  As a special exception, the window
configuration does not record the value of point in the selected window
for the current buffer.

   You can bring back an entire frame layout by restoring a previously
saved window configuration.  If you want to record the layout of all
frames instead of just one, use a frame configuration instead of a
window configuration.  *Note Frame Configurations::.

 -- Function: current-window-configuration &optional frame
     This function returns a new object representing FRAME's current
     window configuration.  The default for FRAME is the selected
     frame.  The variable `window-persistent-parameters' specifies
     which window parameters (if any) are saved by this function.
     *Note Window Parameters::.

 -- Function: set-window-configuration configuration
     This function restores the configuration of windows and buffers as
     specified by CONFIGURATION, for the frame that CONFIGURATION was
     created for.

     The argument CONFIGURATION must be a value that was previously
     returned by `current-window-configuration'.  The configuration is
     restored in the frame from which CONFIGURATION was made, whether
     that frame is selected or not.  This always counts as a window size
     change and triggers execution of the `window-size-change-functions'
     (*note Window Hooks::), because `set-window-configuration' doesn't
     know how to tell whether the new configuration actually differs
     from the old one.

     If the frame from which CONFIGURATION was saved is dead, all this
     function does is restore the three variables `window-min-height',
     `window-min-width' and `minibuffer-scroll-window'.  In this case,
     the function returns `nil'.  Otherwise, it returns `t'.

     Here is a way of using this function to get the same effect as
     `save-window-excursion':

          (let ((config (current-window-configuration)))
            (unwind-protect
                (progn (split-window-below nil)
                       ...)
              (set-window-configuration config)))

 -- Macro: save-window-excursion forms...
     This special form records the window configuration, executes FORMS
     in sequence, then restores the earlier window configuration.  The
     window configuration includes, for each window, the value of point
     and the portion of the buffer that is visible.  It also includes
     the choice of selected window.  However, it does not include the
     value of point in the current buffer; use `save-excursion' also,
     if you wish to preserve that.

     Don't use this construct when `save-selected-window' is sufficient.

     Exit from `save-window-excursion' always triggers execution of
     `window-size-change-functions'.  (It doesn't know how to tell
     whether the restored configuration actually differs from the one in
     effect at the end of the FORMS.)

     The return value is the value of the final form in FORMS.  For
     example:

          (split-window)
               => #<window 25 on control.texi>
          (setq w (selected-window))
               => #<window 19 on control.texi>
          (save-window-excursion
            (delete-other-windows w)
            (switch-to-buffer "foo")
            'do-something)
               => do-something
               ;; The screen is now split again.

 -- Function: window-configuration-p object
     This function returns `t' if OBJECT is a window configuration.

 -- Function: compare-window-configurations config1 config2
     This function compares two window configurations as regards the
     structure of windows, but ignores the values of point and mark and
     the saved scrolling positions--it can return `t' even if those
     aspects differ.

     The function `equal' can also compare two window configurations; it
     regards configurations as unequal if they differ in any respect,
     even a saved point or mark.

 -- Function: window-configuration-frame config
     This function returns the frame for which the window configuration
     CONFIG was made.

   Other primitives to look inside of window configurations would make
sense, but are not implemented because we did not need them.  See the
file `winner.el' for some more operations on windows configurations.

   The objects returned by `current-window-configuration' die together
with the Emacs process.  In order to store a window configuration on
disk and read it back in another Emacs session, you can use the
functions described next.  These functions are also useful to clone the
state of a frame into an arbitrary live window
(`set-window-configuration' effectively clones the windows of a frame
into the root window of that very frame only).

 -- Function: window-state-get &optional window writable
     This function returns the state of WINDOW as a Lisp object.  The
     argument WINDOW can be any window and defaults to the root window
     of the selected frame.

     If the optional argument WRITABLE is non-`nil', this means to not
     use markers for sampling positions like `window-point' or
     `window-start'.  This argument should be non-`nil' when the state
     will be written to disk and read back in another session.

     Together, the argument WRITABLE and the variable
     `window-persistent-parameters' specify which window parameters are
     saved by this function.  *Note Window Parameters::.

   The value returned by `window-state-get' can be used in the same
session to make a clone of a window in another window.  It can be also
written to disk and read back in another session.  In either case, use
the following function to restore the state of the window.

 -- Function: window-state-put state &optional window ignore
     This function puts the window state STATE into WINDOW.  The
     argument STATE should be the state of a window returned by an
     earlier invocation of `window-state-get', see above.  The optional
     argument WINDOW must specify a live window and defaults to the
     selected one.

     If the optional argument IGNORE is non-`nil', it means to ignore
     minimum window sizes and fixed-size restrictions.  If IGNORE is
     `safe', this means windows can get as small as one line and/or two
     columns.


File: elisp,  Node: Window Parameters,  Next: Window Hooks,  Prev: Window Configurations,  Up: Windows

28.24 Window Parameters
=======================

This section describes how window parameters can be used to associate
additional information with windows.

 -- Function: window-parameter window parameter
     This function returns WINDOW's value for PARAMETER.  The default
     for WINDOW is the selected window.  If WINDOW has no setting for
     PARAMETER, this function returns `nil'.

 -- Function: window-parameters &optional window
     This function returns all parameters of WINDOW and their values.
     The default for WINDOW is the selected window.  The return value
     is either `nil', or an association list whose elements have the
     form `(PARAMETER . VALUE)'.

 -- Function: set-window-parameter window parameter value
     This function sets WINDOW's value of PARAMETER to VALUE and
     returns VALUE.  The default for WINDOW is the selected window.

   By default, the functions that save and restore window
configurations or the states of windows (*note Window Configurations::)
do not care about window parameters.  This means that when you change
the value of a parameter within the body of a `save-window-excursion',
the previous value is not restored when that macro exits.  It also means
that when you restore via `window-state-put' a window state saved
earlier by `window-state-get', all cloned windows have their parameters
reset to `nil'.  The following variable allows you to override the
standard behavior:

 -- Variable: window-persistent-parameters
     This variable is an alist specifying which parameters get saved by
     `current-window-configuration' and `window-state-get', and
     subsequently restored by `set-window-configuration' and
     `window-state-put'.  *Note Window Configurations::.

     The CAR of each entry of this alist is a symbol specifying the
     parameter.  The CDR should be one of the following:

    `nil'
          This value means the parameter is saved neither by
          `window-state-get' nor by `current-window-configuration'.

    `t'
          This value specifies that the parameter is saved by
          `current-window-configuration' and (provided its WRITABLE
          argument is `nil') by `window-state-get'.

    `writable'
          This means that the parameter is saved unconditionally by both
          `current-window-configuration' and `window-state-get'.  This
          value should not be used for parameters whose values do not
          have a read syntax.  Otherwise, invoking `window-state-put'
          in another session may fail with an `invalid-read-syntax'
          error.

   Some functions (notably `delete-window', `delete-other-windows' and
`split-window'), may behave specially when their WINDOW argument has a
parameter set.  You can override such special behavior by binding the
following variable to a non-`nil' value:

 -- Variable: ignore-window-parameters
     If this variable is non-`nil', some standard functions do not
     process window parameters.  The functions currently affected by
     this are `split-window', `delete-window', `delete-other-windows',
     and `other-window'.

     An application can bind this variable to a non-`nil' value around
     calls to these functions.  If it does so, the application is fully
     responsible for correctly assigning the parameters of all involved
     windows when exiting that function.

   The following parameters are currently used by the window management
code:

`delete-window'
     This parameter affects the execution of `delete-window' (*note
     Deleting Windows::).

`delete-other-windows'
     This parameter affects the execution of `delete-other-windows'
     (*note Deleting Windows::).

`split-window'
     This parameter affects the execution of `split-window' (*note
     Splitting Windows::).

`other-window'
     This parameter affects the execution of `other-window' (*note
     Cyclic Window Ordering::).

`no-other-window'
     This parameter marks the window as not selectable by `other-window'
     (*note Cyclic Window Ordering::).

`clone-of'
     This parameter specifies the window that this one has been cloned
     from.  It is installed by `window-state-get' (*note Window
     Configurations::).

`quit-restore'
     This parameter specifies what to do with a window when the buffer
     it shows is not needed any more.  It is installed by the buffer
     display functions (*note Choosing Window::), and consulted by the
     function `quit-window' (*note Quitting Windows::).

   There are additional parameters `window-atom' and `window-side';
these are reserved and should not be used by applications.


File: elisp,  Node: Window Hooks,  Prev: Window Parameters,  Up: Windows

28.25 Hooks for Window Scrolling and Changes
============================================

This section describes how a Lisp program can take action whenever a
window displays a different part of its buffer or a different buffer.
There are three actions that can change this: scrolling the window,
switching buffers in the window, and changing the size of the window.
The first two actions run `window-scroll-functions'; the last runs
`window-size-change-functions'.

 -- Variable: window-scroll-functions
     This variable holds a list of functions that Emacs should call
     before redisplaying a window with scrolling.  Displaying a
     different buffer in the window also runs these functions.

     This variable is not a normal hook, because each function is
     called with two arguments: the window, and its new display-start
     position.

     These functions must take care when using `window-end' (*note
     Window Start and End::); if you need an up-to-date value, you must
     use the UPDATE argument to ensure you get it.

     *Warning:* don't use this feature to alter the way the window is
     scrolled.  It's not designed for that, and such use probably won't
     work.

 -- Variable: window-size-change-functions
     This variable holds a list of functions to be called if the size
     of any window changes for any reason.  The functions are called
     just once per redisplay, and just once for each frame on which
     size changes have occurred.

     Each function receives the frame as its sole argument.  There is no
     direct way to find out which windows on that frame have changed
     size, or precisely how.  However, if a size-change function
     records, at each call, the existing windows and their sizes, it
     can also compare the present sizes and the previous sizes.

     Creating or deleting windows counts as a size change, and therefore
     causes these functions to be called.  Changing the frame size also
     counts, because it changes the sizes of the existing windows.

     It is not a good idea to use `save-window-excursion' (*note Window
     Configurations::) in these functions, because that always counts
     as a size change, and it would cause these functions to be called
     over and over.  In most cases, `save-selected-window' (*note
     Selecting Windows::) is what you need here.

 -- Variable: window-configuration-change-hook
     A normal hook that is run every time you change the window
     configuration of an existing frame.  This includes splitting or
     deleting windows, changing the sizes of windows, or displaying a
     different buffer in a window.

     The buffer-local part of this hook is run once for each window on
     the affected frame, with the relevant window selected and its
     buffer current.  The global part is run once for the modified
     frame, with that frame selected.

   In addition, you can use `jit-lock-register' to register a Font Lock
fontification function, which will be called whenever parts of a buffer
are (re)fontified because a window was scrolled or its size changed.
*Note Other Font Lock Variables::.


File: elisp,  Node: Frames,  Next: Positions,  Prev: Windows,  Up: Top

29 Frames
*********

A "frame" is a screen object that contains one or more Emacs windows
(*note Windows::).  It is the kind of object called a "window" in the
terminology of graphical environments; but we can't call it a "window"
here, because Emacs uses that word in a different way.  In Emacs Lisp,
a "frame object" is a Lisp object that represents a frame on the
screen.  *Note Frame Type::.

   A frame initially contains a single main window and/or a minibuffer
window; you can subdivide the main window vertically or horizontally
into smaller windows.  *Note Splitting Windows::.

   A "terminal" is a display device capable of displaying one or more
Emacs frames.  In Emacs Lisp, a "terminal object" is a Lisp object that
represents a terminal.  *Note Terminal Type::.

   There are two classes of terminals: "text terminals" and "graphical
terminals".  Text terminals are non-graphics-capable displays,
including `xterm' and other terminal emulators.  On a text terminal,
each Emacs frame occupies the terminal's entire screen; although you
can create additional frames and switch between them, the terminal only
shows one frame at a time.  Graphical terminals, on the other hand, are
managed by graphical display systems such as the X Window System, which
allow Emacs to show multiple frames simultaneously on the same display.

   On GNU and Unix systems, you can create additional frames on any
available terminal, within a single Emacs session, regardless of
whether Emacs was started on a text or graphical terminal.  Emacs can
display on both graphical and text terminals simultaneously.  This
comes in handy, for instance, when you connect to the same session from
several remote locations.  *Note Multiple Terminals::.

 -- Function: framep object
     This predicate returns a non-`nil' value if OBJECT is a frame, and
     `nil' otherwise.  For a frame, the value indicates which kind of
     display the frame uses:

    `t'
          The frame is displayed on a text terminal.

    `x'
          The frame is displayed on an X graphical terminal.

    `w32'
          The frame is displayed on a MS-Windows graphical terminal.

    `ns'
          The frame is displayed on a GNUstep or Macintosh Cocoa
          graphical terminal.

    `pc'
          The frame is displayed on an MS-DOS terminal.

 -- Function: frame-terminal &optional frame
     This function returns the terminal object that displays FRAME.  If
     FRAME is `nil' or unspecified, it defaults to the selected frame.

 -- Function: terminal-live-p object
     This predicate returns a non-`nil' value if OBJECT is a terminal
     that is live (i.e. not deleted), and `nil' otherwise.  For live
     terminals, the return value indicates what kind of frames are
     displayed on that terminal; the list of possible values is the
     same as for `framep' above.

* Menu:

* Creating Frames::             Creating additional frames.
* Multiple Terminals::          Displaying on several different devices.
* Frame Parameters::            Controlling frame size, position, font, etc.
* Terminal Parameters::         Parameters common for all frames on terminal.
* Frame Titles::                Automatic updating of frame titles.
* Deleting Frames::             Frames last until explicitly deleted.
* Finding All Frames::          How to examine all existing frames.
* Minibuffers and Frames::      How a frame finds the minibuffer to use.
* Input Focus::                 Specifying the selected frame.
* Visibility of Frames::        Frames may be visible or invisible, or icons.
* Raising and Lowering::        Raising a frame makes it hide other windows;
                                  lowering it makes the others hide it.
* Frame Configurations::        Saving the state of all frames.
* Mouse Tracking::              Getting events that say when the mouse moves.
* Mouse Position::              Asking where the mouse is, or moving it.
* Pop-Up Menus::                Displaying a menu for the user to select from.
* Dialog Boxes::                Displaying a box to ask yes or no.
* Pointer Shape::               Specifying the shape of the mouse pointer.
* Window System Selections::    Transferring text to and from other X clients.
* Drag and Drop::               Internals of Drag-and-Drop implementation.
* Color Names::                 Getting the definitions of color names.
* Text Terminal Colors::        Defining colors for text terminals.
* Resources::                   Getting resource values from the server.
* Display Feature Testing::     Determining the features of a terminal.


File: elisp,  Node: Creating Frames,  Next: Multiple Terminals,  Up: Frames

29.1 Creating Frames
====================

To create a new frame, call the function `make-frame'.

 -- Command: make-frame &optional alist
     This function creates and returns a new frame, displaying the
     current buffer.

     The ALIST argument is an alist that specifies frame parameters for
     the new frame.  *Note Frame Parameters::.  If you specify the
     `terminal' parameter in ALIST, the new frame is created on that
     terminal.  Otherwise, if you specify the `window-system' frame
     parameter in ALIST, that determines whether the frame should be
     displayed on a text terminal or a graphical terminal.  *Note
     Window Systems::.  If neither is specified, the new frame is
     created in the same terminal as the selected frame.

     Any parameters not mentioned in ALIST default to the values in the
     alist `default-frame-alist' (*note Initial Parameters::);
     parameters not specified there default from the X resources or its
     equivalent on your operating system (*note X Resources: (emacs)X
     Resources.).  After the frame is created, Emacs applies any
     parameters listed in `frame-inherited-parameters' (see below) and
     not present in the argument, taking the values from the frame that
     was selected when `make-frame' was called.

     This function itself does not make the new frame the selected
     frame.  *Note Input Focus::.  The previously selected frame
     remains selected.  On graphical terminals, however, the windowing
     system may select the new frame for its own reasons.

 -- Variable: before-make-frame-hook
     A normal hook run by `make-frame' before it creates the frame.

 -- Variable: after-make-frame-functions
     An abnormal hook run by `make-frame' after it creates the frame.
     Each function in `after-make-frame-functions' receives one
     argument, the frame just created.

 -- Variable: frame-inherited-parameters
     This variable specifies the list of frame parameters that a newly
     created frame inherits from the currently selected frame.  For each
     parameter (a symbol) that is an element in the list and is not
     present in the argument to `make-frame', the function sets the
     value of that parameter in the created frame to its value in the
     selected frame.


File: elisp,  Node: Multiple Terminals,  Next: Frame Parameters,  Prev: Creating Frames,  Up: Frames

29.2 Multiple Terminals
=======================

Emacs represents each terminal as a "terminal object" data type (*note
Terminal Type::).  On GNU and Unix systems, Emacs can use multiple
terminals simultaneously in each session.  On other systems, it can
only use a single terminal.  Each terminal object has the following
attributes:

   * The name of the device used by the terminal (e.g. `:0.0' or
     `/dev/tty').

   * The terminal and keyboard coding systems used on the terminal.
     *Note Terminal I/O Encoding::.

   * The kind of display associated with the terminal.  This is the
     symbol returned by the function `terminal-live-p' (i.e. `x', `t',
     `w32', `ns', or `pc').  *Note Frames::.

   * A list of terminal parameters.  *Note Terminal Parameters::.

   There is no primitive for creating terminal objects.  Emacs creates
them as needed, such as when you call `make-frame-on-display'
(described below).

 -- Function: terminal-name &optional terminal
     This function returns the file name of the device used by
     TERMINAL.  If TERMINAL is omitted or `nil', it defaults to the
     selected frame's terminal.  TERMINAL can also be a frame, meaning
     that frame's terminal.

 -- Function: terminal-list
     This function returns a list of all live terminal objects.

 -- Function: get-device-terminal device
     This function returns a terminal whose device name is given by
     DEVICE.  If DEVICE is a string, it can be either the file name of
     a terminal device, or the name of an X display of the form
     `HOST:SERVER.SCREEN'.  If DEVICE is a frame, this function returns
     that frame's terminal; `nil' means the selected frame.  Finally,
     if DEVICE is a terminal object that represents a live terminal,
     that terminal is returned.  The function signals an error if its
     argument is none of the above.

 -- Function: delete-terminal &optional terminal force
     This function deletes all frames on TERMINAL and frees the
     resources used by it.  It runs the abnormal hook
     `delete-terminal-functions', passing TERMINAL as the argument to
     each function.

     If TERMINAL is omitted or `nil', it defaults to the selected
     frame's terminal.  TERMINAL can also be a frame, meaning that
     frame's terminal.

     Normally, this function signals an error if you attempt to delete
     the sole active terminal, but if FORCE is non-`nil', you are
     allowed to do so.  Emacs automatically calls this function when the
     last frame on a terminal is deleted (*note Deleting Frames::).

 -- Variable: delete-terminal-functions
     An abnormal hook run by `delete-terminal'.  Each function receives
     one argument, the TERMINAL argument passed to `delete-terminal'.
     Due to technical details, the functions may be called either just
     before the terminal is deleted, or just afterwards.

   A few Lisp variables are "terminal-local"; that is, they have a
separate binding for each terminal.  The binding in effect at any time
is the one for the terminal that the currently selected frame belongs
to.  These variables include `default-minibuffer-frame',
`defining-kbd-macro', `last-kbd-macro', and `system-key-alist'.  They
are always terminal-local, and can never be buffer-local (*note
Buffer-Local Variables::).

   On GNU and Unix systems, each X display is a separate graphical
terminal.  When Emacs is started from within the X window system, it
uses the X display specified by the `DISPLAY' environment variable, or
by the `--display' option (*note Initial Options: (emacs)Initial
Options.).  Emacs can connect to other X displays via the command
`make-frame-on-display'.  Each X display has its own selected frame and
its own minibuffer windows; however, only one of those frames is "_the_
selected frame" at any given moment (*note Input Focus::).  Emacs can
even connect to other text terminals, by interacting with the
`emacsclient' program.  *Note Emacs Server: (emacs)Emacs Server.

   A single X server can handle more than one display.  Each X display
has a three-part name, `HOST:SERVER.SCREEN'.  The first two parts, HOST
and SERVER, identify the X server; the third part, SCREEN, identifies a
screen number on that X server.  When you use two or more screens
belonging to one server, Emacs knows by the similarity in their names
that they share a single keyboard.

   On some "multi-monitor" setups, a single X display outputs to more
than one physical monitor.  Currently, there is no way for Emacs to
distinguish between the different physical monitors.

 -- Command: make-frame-on-display display &optional parameters
     This function creates and returns a new frame on DISPLAY, taking
     the other frame parameters from the alist PARAMETERS.  DISPLAY
     should be the name of an X display (a string).

     Before creating the frame, this function ensures that Emacs is "set
     up" to display graphics.  For instance, if Emacs has not processed
     X resources (e.g. if it was started on a text terminal), it does
     so at this time.  In all other respects, this function behaves like
     `make-frame' (*note Creating Frames::).

 -- Function: x-display-list
     This function returns a list that indicates which X displays Emacs
     has a connection to.  The elements of the list are strings, and
     each one is a display name.

 -- Function: x-open-connection display &optional xrm-string
          must-succeed
     This function opens a connection to the X display DISPLAY, without
     creating a frame on that display.  Normally, Emacs Lisp programs
     need not call this function, as `make-frame-on-display' calls it
     automatically.  The only reason for calling it is to check whether
     communication can be established with a given X display.

     The optional argument XRM-STRING, if not `nil', is a string of
     resource names and values, in the same format used in the
     `.Xresources' file.  *Note X Resources: (emacs)X Resources.  These
     values apply to all Emacs frames created on this display,
     overriding the resource values recorded in the X server.  Here's
     an example of what this string might look like:

          "*BorderWidth: 3\n*InternalBorder: 2\n"

     If MUST-SUCCEED is non-`nil', failure to open the connection
     terminates Emacs.  Otherwise, it is an ordinary Lisp error.

 -- Function: x-close-connection display
     This function closes the connection to display DISPLAY.  Before
     you can do this, you must first delete all the frames that were
     open on that display (*note Deleting Frames::).


File: elisp,  Node: Frame Parameters,  Next: Terminal Parameters,  Prev: Multiple Terminals,  Up: Frames

29.3 Frame Parameters
=====================

A frame has many parameters that control its appearance and behavior.
Just what parameters a frame has depends on what display mechanism it
uses.

   Frame parameters exist mostly for the sake of graphical displays.
Most frame parameters have no effect when applied to a frame on a text
terminal; only the `height', `width', `name', `title',
`menu-bar-lines', `buffer-list' and `buffer-predicate' parameters do
something special.  If the terminal supports colors, the parameters
`foreground-color', `background-color', `background-mode' and
`display-type' are also meaningful.  If the terminal supports frame
transparency, the parameter `alpha' is also meaningful.

* Menu:

* Parameter Access::       How to change a frame's parameters.
* Initial Parameters::     Specifying frame parameters when you make a frame.
* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position::      Changing the size and position of a frame.
* Geometry::               Parsing geometry specifications.


File: elisp,  Node: Parameter Access,  Next: Initial Parameters,  Up: Frame Parameters

29.3.1 Access to Frame Parameters
---------------------------------

These functions let you read and change the parameter values of a frame.

 -- Function: frame-parameter frame parameter
     This function returns the value of the parameter PARAMETER (a
     symbol) of FRAME.  If FRAME is `nil', it returns the selected
     frame's parameter.  If FRAME has no setting for PARAMETER, this
     function returns `nil'.

 -- Function: frame-parameters &optional frame
     The function `frame-parameters' returns an alist listing all the
     parameters of FRAME and their values.  If FRAME is `nil' or
     omitted, this returns the selected frame's parameters

 -- Function: modify-frame-parameters frame alist
     This function alters the parameters of frame FRAME based on the
     elements of ALIST.  Each element of ALIST has the form `(PARM .
     VALUE)', where PARM is a symbol naming a parameter.  If you don't
     mention a parameter in ALIST, its value doesn't change.  If FRAME
     is `nil', it defaults to the selected frame.

 -- Function: set-frame-parameter frame parm value
     This function sets the frame parameter PARM to the specified
     VALUE.  If FRAME is `nil', it defaults to the selected frame.

 -- Function: modify-all-frames-parameters alist
     This function alters the frame parameters of all existing frames
     according to ALIST, then modifies `default-frame-alist' (and, if
     necessary, `initial-frame-alist') to apply the same parameter
     values to frames that will be created henceforth.


File: elisp,  Node: Initial Parameters,  Next: Window Frame Parameters,  Prev: Parameter Access,  Up: Frame Parameters

29.3.2 Initial Frame Parameters
-------------------------------

You can specify the parameters for the initial startup frame by setting
`initial-frame-alist' in your init file (*note Init File::).

 -- User Option: initial-frame-alist
     This variable's value is an alist of parameter values used when
     creating the initial frame.  You can set this variable to specify
     the appearance of the initial frame without altering subsequent
     frames.  Each element has the form:

          (PARAMETER . VALUE)

     Emacs creates the initial frame before it reads your init file.
     After reading that file, Emacs checks `initial-frame-alist', and
     applies the parameter settings in the altered value to the already
     created initial frame.

     If these settings affect the frame geometry and appearance, you'll
     see the frame appear with the wrong ones and then change to the
     specified ones.  If that bothers you, you can specify the same
     geometry and appearance with X resources; those do take effect
     before the frame is created.  *Note X Resources: (emacs)X
     Resources.

     X resource settings typically apply to all frames.  If you want to
     specify some X resources solely for the sake of the initial frame,
     and you don't want them to apply to subsequent frames, here's how
     to achieve this.  Specify parameters in `default-frame-alist' to
     override the X resources for subsequent frames; then, to prevent
     these from affecting the initial frame, specify the same
     parameters in `initial-frame-alist' with values that match the X
     resources.

   If these parameters specify a separate "minibuffer-only frame" with
`(minibuffer . nil)', and you have not created one, Emacs creates one
for you.

 -- User Option: minibuffer-frame-alist
     This variable's value is an alist of parameter values used when
     creating an initial minibuffer-only frame.  This is the
     minibuffer-only frame that Emacs creates if `initial-frame-alist'
     specifies a frame with no minibuffer.

 -- User Option: default-frame-alist
     This is an alist specifying default values of frame parameters for
     all Emacs frames--the first frame, and subsequent frames.  When
     using the X Window System, you can get the same results by means
     of X resources in many cases.

     Setting this variable does not affect existing frames.

   Functions that display a buffer in a separate frame can override the
default parameters by supplying their own parameters.  *Note Definition
of special-display-frame-alist::.

   If you invoke Emacs with command-line options that specify frame
appearance, those options take effect by adding elements to either
`initial-frame-alist' or `default-frame-alist'.  Options which affect
just the initial frame, such as `-geometry' and `--maximized', add to
`initial-frame-alist'; the others add to `default-frame-alist'.  *note
Command Line Arguments for Emacs Invocation: (emacs)Emacs Invocation.


File: elisp,  Node: Window Frame Parameters,  Next: Size and Position,  Prev: Initial Parameters,  Up: Frame Parameters

29.3.3 Window Frame Parameters
------------------------------

Just what parameters a frame has depends on what display mechanism it
uses.  This section describes the parameters that have special meanings
on some or all kinds of terminals.  Of these, `name', `title',
`height', `width', `buffer-list' and `buffer-predicate' provide
meaningful information in terminal frames, and `tty-color-mode' is
meaningful only for frames on text terminals.

* Menu:

* Basic Parameters::            Parameters that are fundamental.
* Position Parameters::         The position of the frame on the screen.
* Size Parameters::             Frame's size.
* Layout Parameters::           Size of parts of the frame, and
                                  enabling or disabling some parts.
* Buffer Parameters::           Which buffers have been or should be shown.
* Management Parameters::       Communicating with the window manager.
* Cursor Parameters::           Controlling the cursor appearance.
* Font and Color Parameters::   Fonts and colors for the frame text.


File: elisp,  Node: Basic Parameters,  Next: Position Parameters,  Up: Window Frame Parameters

29.3.3.1 Basic Parameters
.........................

These frame parameters give the most basic information about the frame.
`title' and `name' are meaningful on all terminals.

`display'
     The display on which to open this frame.  It should be a string of
     the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
     variable.

`display-type'
     This parameter describes the range of possible colors that can be
     used in this frame.  Its value is `color', `grayscale' or `mono'.

`title'
     If a frame has a non-`nil' title, it appears in the window
     system's title bar at the top of the frame, and also in the mode
     line of windows in that frame if `mode-line-frame-identification'
     uses `%F' (*note %-Constructs::).  This is normally the case when
     Emacs is not using a window system, and can only display one frame
     at a time.  *Note Frame Titles::.

`name'
     The name of the frame.  The frame name serves as a default for the
     frame title, if the `title' parameter is unspecified or `nil'.  If
     you don't specify a name, Emacs sets the frame name automatically
     (*note Frame Titles::).

     If you specify the frame name explicitly when you create the
     frame, the name is also used (instead of the name of the Emacs
     executable) when looking up X resources for the frame.

`explicit-name'
     If the frame name was specified explicitly when the frame was
     created, this parameter will be that name.  If the frame wasn't
     explicitly named, this parameter will be `nil'.


File: elisp,  Node: Position Parameters,  Next: Size Parameters,  Prev: Basic Parameters,  Up: Window Frame Parameters

29.3.3.2 Position Parameters
............................

Position parameters' values are normally measured in pixels, but on
text terminals they count characters or lines instead.

`left'
     The position, in pixels, of the left (or right) edge of the frame
     with respect to the left (or right) edge of the screen.  The value
     may be:

    an integer
          A positive integer relates the left edge of the frame to the
          left edge of the screen.  A negative integer relates the
          right frame edge to the right screen edge.

    `(+ POS)'
          This specifies the position of the left frame edge relative
          to the left screen edge.  The integer POS may be positive or
          negative; a negative value specifies a position outside the
          screen.

    `(- POS)'
          This specifies the position of the right frame edge relative
          to the right screen edge.  The integer POS may be positive or
          negative; a negative value specifies a position outside the
          screen.

     Some window managers ignore program-specified positions.  If you
     want to be sure the position you specify is not ignored, specify a
     non-`nil' value for the `user-position' parameter as well.

`top'
     The screen position of the top (or bottom) edge, in pixels, with
     respect to the top (or bottom) edge of the screen.  It works just
     like `left', except vertically instead of horizontally.

`icon-left'
     The screen position of the left edge of the frame's icon, in
     pixels, counting from the left edge of the screen.  This takes
     effect when the frame is iconified, if the window manager supports
     this feature.  If you specify a value for this parameter, then you
     must also specify a value for `icon-top' and vice versa.

`icon-top'
     The screen position of the top edge of the frame's icon, in pixels,
     counting from the top edge of the screen.  This takes effect when
     the frame is iconified, if the window manager supports this
     feature.

`user-position'
     When you create a frame and specify its screen position with the
     `left' and `top' parameters, use this parameter to say whether the
     specified position was user-specified (explicitly requested in some
     way by a human user) or merely program-specified (chosen by a
     program).  A non-`nil' value says the position was user-specified.

     Window managers generally heed user-specified positions, and some
     heed program-specified positions too.  But many ignore
     program-specified positions, placing the window in a default
     fashion or letting the user place it with the mouse.  Some window
     managers, including `twm', let the user specify whether to obey
     program-specified positions or ignore them.

     When you call `make-frame', you should specify a non-`nil' value
     for this parameter if the values of the `left' and `top'
     parameters represent the user's stated preference; otherwise, use
     `nil'.


File: elisp,  Node: Size Parameters,  Next: Layout Parameters,  Prev: Position Parameters,  Up: Window Frame Parameters

29.3.3.3 Size Parameters
........................

Frame parameters specify frame sizes in character units.  On graphical
displays, the `default' face determines the actual pixel sizes of these
character units (*note Face Attributes::).

`height'
     The height of the frame contents, in characters.  (To get the
     height in pixels, call `frame-pixel-height'; see *note Size and
     Position::.)

`width'
     The width of the frame contents, in characters.  (To get the width
     in pixels, call `frame-pixel-width'; see *note Size and
     Position::.)

`user-size'
     This does for the size parameters `height' and `width' what the
     `user-position' parameter (*note user-position: Position
     Parameters.) does for the position parameters `top' and `left'.

`fullscreen'
     Specify that width, height or both shall be maximized.  The value
     `fullwidth' specifies that width shall be as wide as possible.
     The value `fullheight' specifies that height shall be as tall as
     possible.  The value `fullboth' specifies that both the width and
     the height shall be set to the size of the screen.  The value
     `maximized' specifies that the frame shall be maximized.  The
     difference between `maximized' and `fullboth' is that the former
     still has window manager decorations while the latter really
     covers the whole screen.


File: elisp,  Node: Layout Parameters,  Next: Buffer Parameters,  Prev: Size Parameters,  Up: Window Frame Parameters

29.3.3.4 Layout Parameters
..........................

These frame parameters enable or disable various parts of the frame, or
control their sizes.

`border-width'
     The width in pixels of the frame's border.

`internal-border-width'
     The distance in pixels between text (or fringe) and the frame's
     border.

`vertical-scroll-bars'
     Whether the frame has scroll bars for vertical scrolling, and
     which side of the frame they should be on.  The possible values
     are `left', `right', and `nil' for no scroll bars.

`scroll-bar-width'
     The width of vertical scroll bars, in pixels, or `nil' meaning to
     use the default width.

`left-fringe'
`right-fringe'
     The default width of the left and right fringes of windows in this
     frame (*note Fringes::).  If either of these is zero, that
     effectively removes the corresponding fringe.

     When you use `frame-parameter' to query the value of either of
     these two frame parameters, the return value is always an integer.
     When using `set-frame-parameter', passing a `nil' value imposes an
     actual default value of 8 pixels.

     The combined fringe widths must add up to an integral number of
     columns, so the actual default fringe widths for the frame, as
     reported by `frame-parameter', may be larger than what you
     specify.  Any extra width is distributed evenly between the left
     and right fringe.  However, you can force one fringe or the other
     to a precise width by specifying that width as a negative integer.
     If both widths are negative, only the left fringe gets the
     specified width.

`menu-bar-lines'
     The number of lines to allocate at the top of the frame for a menu
     bar.  The default is 1 if Menu Bar mode is enabled, and 0
     otherwise.  *Note Menu Bars: (emacs)Menu Bars.

`tool-bar-lines'
     The number of lines to use for the tool bar.  The default is 1 if
     Tool Bar mode is enabled, and 0 otherwise.  *Note Tool Bars:
     (emacs)Tool Bars.

`tool-bar-position'
     The position of the tool bar.  Currently only for the GTK tool bar.
     Value can be one of `top', `bottom' `left', `right'.  The default
     is  `top'.

`line-spacing'
     Additional space to leave below each text line, in pixels (a
     positive integer).  *Note Line Height::, for more information.


File: elisp,  Node: Buffer Parameters,  Next: Management Parameters,  Prev: Layout Parameters,  Up: Window Frame Parameters

29.3.3.5 Buffer Parameters
..........................

These frame parameters, meaningful on all kinds of terminals, deal with
which buffers have been, or should, be displayed in the frame.

`minibuffer'
     Whether this frame has its own minibuffer.  The value `t' means
     yes, `nil' means no, `only' means this frame is just a minibuffer.
     If the value is a minibuffer window (in some other frame), the
     frame uses that minibuffer.

     This frame parameter takes effect when the frame is created, and
     can not be changed afterwards.

`buffer-predicate'
     The buffer-predicate function for this frame.  The function
     `other-buffer' uses this predicate (from the selected frame) to
     decide which buffers it should consider, if the predicate is not
     `nil'.  It calls the predicate with one argument, a buffer, once
     for each buffer; if the predicate returns a non-`nil' value, it
     considers that buffer.

`buffer-list'
     A list of buffers that have been selected in this frame, ordered
     most-recently-selected first.

`unsplittable'
     If non-`nil', this frame's window is never split automatically.


File: elisp,  Node: Management Parameters,  Next: Cursor Parameters,  Prev: Buffer Parameters,  Up: Window Frame Parameters

29.3.3.6 Window Management Parameters
.....................................

The following frame parameters control various aspects of the frame's
interaction with the window manager.  They have no effect on text
terminals.

`visibility'
     The state of visibility of the frame.  There are three
     possibilities: `nil' for invisible, `t' for visible, and `icon' for
     iconified.  *Note Visibility of Frames::.

`auto-raise'
     If non-`nil', Emacs automatically raises the frame when it is
     selected.  Some window managers do not allow this.

`auto-lower'
     If non-`nil', Emacs automatically lowers the frame when it is
     deselected.  Some window managers do not allow this.

`icon-type'
     The type of icon to use for this frame.  If the value is a string,
     that specifies a file containing a bitmap to use; `nil' specifies
     no icon (in which case the window manager decides what to show);
     any other non-`nil' value specifies the default Emacs icon.

`icon-name'
     The name to use in the icon for this frame, when and if the icon
     appears.  If this is `nil', the frame's title is used.

`window-id'
     The ID number which the graphical display uses for this frame.
     Emacs assigns this parameter when the frame is created; changing
     the parameter has no effect on the actual ID number.

`outer-window-id'
     The ID number of the outermost window-system window in which the
     frame exists.  As with `window-id', changing this parameter has no
     actual effect.

`wait-for-wm'
     If non-`nil', tell Xt to wait for the window manager to confirm
     geometry changes.  Some window managers, including versions of
     Fvwm2 and KDE, fail to confirm, so Xt hangs.  Set this to `nil' to
     prevent hanging with those window managers.

`sticky'
     If non-`nil', the frame is visible on all virtual desktops on
     systems with virtual desktops.



File: elisp,  Node: Cursor Parameters,  Next: Font and Color Parameters,  Prev: Management Parameters,  Up: Window Frame Parameters

29.3.3.7 Cursor Parameters
..........................

This frame parameter controls the way the cursor looks.

`cursor-type'
     How to display the cursor.  Legitimate values are:

    `box'
          Display a filled box.  (This is the default.)

    `hollow'
          Display a hollow box.

    `nil'
          Don't display a cursor.

    `bar'
          Display a vertical bar between characters.

    `(bar . WIDTH)'
          Display a vertical bar WIDTH pixels wide between characters.

    `hbar'
          Display a horizontal bar.

    `(hbar . HEIGHT)'
          Display a horizontal bar HEIGHT pixels high.

   The `cursor-type' frame parameter may be overridden by the variables
`cursor-type' and `cursor-in-non-selected-windows':

 -- Variable: cursor-type
     This buffer-local variable controls how the cursor looks in a
     selected window showing the buffer.  If its value is `t', that
     means to use the cursor specified by the `cursor-type' frame
     parameter.  Otherwise, the value should be one of the cursor types
     listed above, and it overrides the `cursor-type' frame parameter.

 -- User Option: cursor-in-non-selected-windows
     This buffer-local variable controls how the cursor looks in a
     window that is not selected.  It supports the same values as the
     `cursor-type' frame parameter; also, `nil' means don't display a
     cursor in nonselected windows, and `t' (the default) means use a
     standard modification of the usual cursor type (solid box becomes
     hollow box, and bar becomes a narrower bar).

 -- User Option: blink-cursor-alist
     This variable specifies how to blink the cursor.  Each element has
     the form `(ON-STATE . OFF-STATE)'.  Whenever the cursor type
     equals ON-STATE (comparing using `equal'), the corresponding
     OFF-STATE specifies what the cursor looks like when it blinks
     "off".  Both ON-STATE and OFF-STATE should be suitable values for
     the `cursor-type' frame parameter.

     There are various defaults for how to blink each type of cursor, if
     the type is not mentioned as an ON-STATE here.  Changes in this
     variable do not take effect immediately, only when you specify the
     `cursor-type' frame parameter.


File: elisp,  Node: Font and Color Parameters,  Prev: Cursor Parameters,  Up: Window Frame Parameters

29.3.3.8 Font and Color Parameters
..................................

These frame parameters control the use of fonts and colors.

`font-backend'
     A list of symbols, specifying the "font backends" to use for
     drawing fonts in the frame, in order of priority.  On X, there are
     currently two available font backends: `x' (the X core font
     driver) and `xft' (the Xft font driver).  On Windows, there are
     currently two available font backends: `gdi' and `uniscribe'
     (*note Windows Fonts: (emacs)Windows Fonts.).  On other systems,
     there is only one available font backend, so it does not make
     sense to modify this frame parameter.

`background-mode'
     This parameter is either `dark' or `light', according to whether
     the background color is a light one or a dark one.

`tty-color-mode'
     This parameter overrides the terminal's color support as given by
     the system's terminal capabilities database in that this
     parameter's value specifies the color mode to use on a text
     terminal.  The value can be either a symbol or a number.  A number
     specifies the number of colors to use (and, indirectly, what
     commands to issue to produce each color).  For example,
     `(tty-color-mode . 8)' specifies use of the ANSI escape sequences
     for 8 standard text colors.  A value of -1 turns off color support.

     If the parameter's value is a symbol, it specifies a number through
     the value of `tty-color-mode-alist', and the associated number is
     used instead.

`screen-gamma'
     If this is a number, Emacs performs "gamma correction" which
     adjusts the brightness of all colors.  The value should be the
     screen gamma of your display, a floating point number.

     Usual PC monitors have a screen gamma of 2.2, so color values in
     Emacs, and in X windows generally, are calibrated to display
     properly on a monitor with that gamma value.  If you specify 2.2
     for `screen-gamma', that means no correction is needed.  Other
     values request correction, designed to make the corrected colors
     appear on your screen the way they would have appeared without
     correction on an ordinary monitor with a gamma value of 2.2.

     If your monitor displays colors too light, you should specify a
     `screen-gamma' value smaller than 2.2.  This requests correction
     that makes colors darker.  A screen gamma value of 1.5 may give
     good results for LCD color displays.

`alpha'
     This parameter specifies the opacity of the frame, on graphical
     displays that support variable opacity.  It should be an integer
     between 0 and 100, where 0 means completely transparent and 100
     means completely opaque.  It can also have a `nil' value, which
     tells Emacs not to set the frame opacity (leaving it to the window
     manager).

     To prevent the frame from disappearing completely from view, the
     variable `frame-alpha-lower-limit' defines a lower opacity limit.
     If the value of the frame parameter is less than the value of this
     variable, Emacs uses the latter.  By default,
     `frame-alpha-lower-limit' is 20.

     The `alpha' frame parameter can also be a cons cell `(`active' .
     `inactive')', where `active' is the opacity of the frame when it
     is selected, and `inactive' is the opacity when it is not selected.

   The following frame parameters are semi-obsolete in that they are
automatically equivalent to particular face attributes of particular
faces (*note Standard Faces: (emacs)Standard Faces.):

`font'
     The name of the font for displaying text in the frame.  This is a
     string, either a valid font name for your system or the name of an
     Emacs fontset (*note Fontsets::).  It is equivalent to the `font'
     attribute of the `default' face.

`foreground-color'
     The color to use for the image of a character.  It is equivalent to
     the `:foreground' attribute of the `default' face.

`background-color'
     The color to use for the background of characters.  It is
     equivalent to the `:background' attribute of the `default' face.

`mouse-color'
     The color for the mouse pointer.  It is equivalent to the
     `:background' attribute of the `mouse' face.

`cursor-color'
     The color for the cursor that shows point.  It is equivalent to the
     `:background' attribute of the `cursor' face.

`border-color'
     The color for the border of the frame.  It is equivalent to the
     `:background' attribute of the `border' face.

`scroll-bar-foreground'
     If non-`nil', the color for the foreground of scroll bars.  It is
     equivalent to the `:foreground' attribute of the `scroll-bar' face.

`scroll-bar-background'
     If non-`nil', the color for the background of scroll bars.  It is
     equivalent to the `:background' attribute of the `scroll-bar' face.


File: elisp,  Node: Size and Position,  Next: Geometry,  Prev: Window Frame Parameters,  Up: Frame Parameters

29.3.4 Frame Size And Position
------------------------------

You can read or change the size and position of a frame using the frame
parameters `left', `top', `height', and `width'.  Whatever geometry
parameters you don't specify are chosen by the window manager in its
usual fashion.

   Here are some special features for working with sizes and positions.
(For the precise meaning of "selected frame" used by these functions,
see *note Input Focus::.)

 -- Function: set-frame-position frame left top
     This function sets the position of the top left corner of FRAME to
     LEFT and TOP.  These arguments are measured in pixels, and
     normally count from the top left corner of the screen.

     Negative parameter values position the bottom edge of the window
     up from the bottom edge of the screen, or the right window edge to
     the left of the right edge of the screen.  It would probably be
     better if the values were always counted from the left and top, so
     that negative arguments would position the frame partly off the
     top or left edge of the screen, but it seems inadvisable to change
     that now.

 -- Function: frame-height &optional frame
 -- Function: frame-width &optional frame
     These functions return the height and width of FRAME, measured in
     lines and columns.  If you don't supply FRAME, they use the
     selected frame.

 -- Function: frame-pixel-height &optional frame
 -- Function: frame-pixel-width &optional frame
     These functions return the height and width of the main display
     area of FRAME, measured in pixels.  If you don't supply FRAME,
     they use the selected frame.  For a text terminal, the results are
     in characters rather than pixels.

     These values include the internal borders, and windows' scroll bars
     and fringes (which belong to individual windows, not to the frame
     itself).  The exact value of the heights depends on the
     window-system and toolkit in use.  With GTK+, the height does not
     include any tool bar or menu bar.  With the Motif or Lucid
     toolkits, it includes the tool bar but not the menu bar.  In a
     graphical version with no toolkit, it includes both the tool bar
     and menu bar.  For a text terminal, the result includes the menu
     bar.

 -- Function: frame-char-height &optional frame
 -- Function: frame-char-width &optional frame
     These functions return the height and width of a character in
     FRAME, measured in pixels.  The values depend on the choice of
     font.  If you don't supply FRAME, these functions use the selected
     frame.

 -- Function: set-frame-size frame cols rows
     This function sets the size of FRAME, measured in characters; COLS
     and ROWS specify the new width and height.

     To set the size based on values measured in pixels, use
     `frame-char-height' and `frame-char-width' to convert them to
     units of characters.

 -- Function: set-frame-height frame lines &optional pretend
     This function resizes FRAME to a height of LINES lines.  The sizes
     of existing windows in FRAME are altered proportionally to fit.

     If PRETEND is non-`nil', then Emacs displays LINES lines of output
     in FRAME, but does not change its value for the actual height of
     the frame.  This is only useful on text terminals.  Using a
     smaller height than the terminal actually implements may be useful
     to reproduce behavior observed on a smaller screen, or if the
     terminal malfunctions when using its whole screen.  Setting the
     frame height "for real" does not always work, because knowing the
     correct actual size may be necessary for correct cursor
     positioning on text terminals.

 -- Function: set-frame-width frame width &optional pretend
     This function sets the width of FRAME, measured in characters.
     The argument PRETEND has the same meaning as in `set-frame-height'.


File: elisp,  Node: Geometry,  Prev: Size and Position,  Up: Frame Parameters

29.3.5 Geometry
---------------

Here's how to examine the data in an X-style window geometry
specification:

 -- Function: x-parse-geometry geom
     The function `x-parse-geometry' converts a standard X window
     geometry string to an alist that you can use as part of the
     argument to `make-frame'.

     The alist describes which parameters were specified in GEOM, and
     gives the values specified for them.  Each element looks like
     `(PARAMETER . VALUE)'.  The possible PARAMETER values are `left',
     `top', `width', and `height'.

     For the size parameters, the value must be an integer.  The
     position parameter names `left' and `top' are not totally accurate,
     because some values indicate the position of the right or bottom
     edges instead.  The VALUE possibilities for the position
     parameters are: an integer, a list `(+ POS)', or a list `(- POS)';
     as previously described (*note Position Parameters::).

     Here is an example:

          (x-parse-geometry "35x70+0-0")
               => ((height . 70) (width . 35)
                   (top - 0) (left . 0))


File: elisp,  Node: Terminal Parameters,  Next: Frame Titles,  Prev: Frame Parameters,  Up: Frames

29.4 Terminal Parameters
========================

Each terminal has a list of associated parameters.  These "terminal
parameters" are mostly a convenient way of storage for terminal-local
variables, but some terminal parameters have a special meaning.

   This section describes functions to read and change the parameter
values of a terminal.  They all accept as their argument either a
terminal or a frame; the latter means use that frame's terminal.  An
argument of `nil' means the selected frame's terminal.

 -- Function: terminal-parameters &optional terminal
     This function returns an alist listing all the parameters of
     TERMINAL and their values.

 -- Function: terminal-parameter terminal parameter
     This function returns the value of the parameter PARAMETER (a
     symbol) of TERMINAL.  If TERMINAL has no setting for PARAMETER,
     this function returns `nil'.

 -- Function: set-terminal-parameter terminal parameter value
     This function sets the parameter PARM of TERMINAL to the specified
     VALUE, and returns the previous value of that parameter.

   Here's a list of a few terminal parameters that have a special
meaning:

`background-mode'
     The classification of the terminal's background color, either
     `light' or `dark'.

`normal-erase-is-backspace'
     Value is either 1 or 0, depending on whether
     `normal-erase-is-backspace-mode' is turned on or off on this
     terminal.  *Note DEL Does Not Delete: (emacs)DEL Does Not Delete.

`terminal-initted'
     After the terminal is initialized, this is set to the
     terminal-specific initialization function.


File: elisp,  Node: Frame Titles,  Next: Deleting Frames,  Prev: Terminal Parameters,  Up: Frames

29.5 Frame Titles
=================

Every frame has a `name' parameter; this serves as the default for the
frame title which window systems typically display at the top of the
frame.  You can specify a name explicitly by setting the `name' frame
property.

   Normally you don't specify the name explicitly, and Emacs computes
the frame name automatically based on a template stored in the variable
`frame-title-format'.  Emacs recomputes the name each time the frame is
redisplayed.

 -- Variable: frame-title-format
     This variable specifies how to compute a name for a frame when you
     have not explicitly specified one.  The variable's value is
     actually a mode line construct, just like `mode-line-format',
     except that the `%c' and `%l' constructs are ignored.  *Note Mode
     Line Data::.

 -- Variable: icon-title-format
     This variable specifies how to compute the name for an iconified
     frame, when you have not explicitly specified the frame title.
     This title appears in the icon itself.

 -- Variable: multiple-frames
     This variable is set automatically by Emacs.  Its value is `t' when
     there are two or more frames (not counting minibuffer-only frames
     or invisible frames).  The default value of `frame-title-format'
     uses `multiple-frames' so as to put the buffer name in the frame
     title only when there is more than one frame.

     The value of this variable is not guaranteed to be accurate except
     while processing `frame-title-format' or `icon-title-format'.


File: elisp,  Node: Deleting Frames,  Next: Finding All Frames,  Prev: Frame Titles,  Up: Frames

29.6 Deleting Frames
====================

A "live frame" is one that has not been deleted.  When a frame is
deleted, it is removed from its terminal display, although it may
continue to exist as a Lisp object until there are no more references
to it.

 -- Command: delete-frame &optional frame force
     This function deletes the frame FRAME.  Unless FRAME is a tooltip,
     it first runs the hook `delete-frame-functions' (each function
     gets one argument, FRAME).  By default, FRAME is the selected
     frame.

     A frame cannot be deleted if its minibuffer is used by other
     frames.  Normally, you cannot delete a frame if all other frames
     are invisible, but if FORCE is non-`nil', then you are allowed to
     do so.

 -- Function: frame-live-p frame
     The function `frame-live-p' returns non-`nil' if the frame FRAME
     has not been deleted.  The possible non-`nil' return values are
     like those of `framep'.  *Note Frames::.

   Some window managers provide a command to delete a window.  These
work by sending a special message to the program that operates the
window.  When Emacs gets one of these commands, it generates a
`delete-frame' event, whose normal definition is a command that calls
the function `delete-frame'.  *Note Misc Events::.


File: elisp,  Node: Finding All Frames,  Next: Minibuffers and Frames,  Prev: Deleting Frames,  Up: Frames

29.7 Finding All Frames
=======================

 -- Function: frame-list
     This function returns a list of all the live frames, i.e. those
     that have not been deleted.  It is analogous to `buffer-list' for
     buffers, and includes frames on all terminals.  The list that you
     get is newly created, so modifying the list doesn't have any
     effect on the internals of Emacs.

 -- Function: visible-frame-list
     This function returns a list of just the currently visible frames.
     *Note Visibility of Frames::.  Frames on text terminals always
     count as "visible", even though only the selected one is actually
     displayed.

 -- Function: next-frame &optional frame minibuf
     This function lets you cycle conveniently through all the frames on
     the current display from an arbitrary starting point.  It returns
     the "next" frame after FRAME in the cycle.  If FRAME is omitted or
     `nil', it defaults to the selected frame (*note Input Focus::).

     The second argument, MINIBUF, says which frames to consider:

    `nil'
          Exclude minibuffer-only frames.

    `visible'
          Consider all visible frames.

    0
          Consider all visible or iconified frames.

    a window
          Consider only the frames using that particular window as their
          minibuffer.

    anything else
          Consider all frames.

 -- Function: previous-frame &optional frame minibuf
     Like `next-frame', but cycles through all frames in the opposite
     direction.

   See also `next-window' and `previous-window', in *note Cyclic Window
Ordering::.


File: elisp,  Node: Minibuffers and Frames,  Next: Input Focus,  Prev: Finding All Frames,  Up: Frames

29.8 Minibuffers and Frames
===========================

Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected.  If the frame has a minibuffer,
you can get it with `minibuffer-window' (*note Definition of
minibuffer-window::).

   However, you can also create a frame with no minibuffer.  Such a
frame must use the minibuffer window of some other frame.  When you
create the frame, you can explicitly specify the minibuffer window to
use (in some other frame).  If you don't, then the minibuffer is found
in the frame which is the value of the variable
`default-minibuffer-frame'.  Its value should be a frame that does have
a minibuffer.

   If you use a minibuffer-only frame, you might want that frame to
raise when you enter the minibuffer.  If so, set the variable
`minibuffer-auto-raise' to `t'.  *Note Raising and Lowering::.

 -- Variable: default-minibuffer-frame
     This variable specifies the frame to use for the minibuffer
     window, by default.  It does not affect existing frames.  It is
     always local to the current terminal and cannot be buffer-local.
     *Note Multiple Terminals::.


File: elisp,  Node: Input Focus,  Next: Visibility of Frames,  Prev: Minibuffers and Frames,  Up: Frames

29.9 Input Focus
================

At any time, one frame in Emacs is the "selected frame".  The selected
window always resides on the selected frame.

   When Emacs displays its frames on several terminals (*note Multiple
Terminals::), each terminal has its own selected frame.  But only one
of these is "_the_ selected frame": it's the frame that belongs to the
terminal from which the most recent input came.  That is, when Emacs
runs a command that came from a certain terminal, the selected frame is
the one of that terminal.  Since Emacs runs only a single command at
any given time, it needs to consider only one selected frame at a time;
this frame is what we call "the selected frame" in this manual.  The
display on which the selected frame is shown is the "selected frame's
display".

 -- Function: selected-frame
     This function returns the selected frame.

   Some window systems and window managers direct keyboard input to the
window object that the mouse is in; others require explicit clicks or
commands to "shift the focus" to various window objects.  Either way,
Emacs automatically keeps track of which frame has the focus.  To
explicitly switch to a different frame from a Lisp function, call
`select-frame-set-input-focus'.

   Lisp programs can also switch frames "temporarily" by calling the
function `select-frame'.  This does not alter the window system's
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.

   When using a text terminal, only one frame can be displayed at a time
on the terminal, so after a call to `select-frame', the next redisplay
actually displays the newly selected frame.  This frame remains
selected until a subsequent call to `select-frame'.  Each frame on a
text terminal has a number which appears in the mode line before the
buffer name (*note Mode Line Variables::).

 -- Function: select-frame-set-input-focus frame &optional norecord
     This function selects FRAME, raises it (should it happen to be
     obscured by other frames) and tries to give it the X server's
     focus.  On a text terminal, the next redisplay displays the new
     frame on the entire terminal screen.  The optional argument
     NORECORD has the same meaning as for `select-frame' (see below).
     The return value of this function is not significant.

 -- Command: select-frame frame &optional norecord
     This function selects frame FRAME, temporarily disregarding the
     focus of the X server if any.  The selection of FRAME lasts until
     the next time the user does something to select a different frame,
     or until the next time this function is called.  (If you are using
     a window system, the previously selected frame may be restored as
     the selected frame after return to the command loop, because it
     still may have the window system's input focus.)

     The specified FRAME becomes the selected frame, and its terminal
     becomes the selected terminal.  This function then calls
     `select-window' as a subroutine, passing the window selected
     within FRAME as its first argument and NORECORD as its second
     argument (hence, if NORECORD is non-`nil', this avoids changing
     the order of recently selected windows nor the buffer list).
     *Note Selecting Windows::.

     This function returns FRAME, or `nil' if FRAME has been deleted.

     In general, you should never use `select-frame' in a way that
     could switch to a different terminal without switching back when
     you're done.

   Emacs cooperates with the window system by arranging to select
frames as the server and window manager request.  It does so by
generating a special kind of input event, called a "focus" event, when
appropriate.  The command loop handles a focus event by calling
`handle-switch-frame'.  *Note Focus Events::.

 -- Command: handle-switch-frame frame
     This function handles a focus event by selecting frame FRAME.

     Focus events normally do their job by invoking this command.
     Don't call it for any other reason.

 -- Function: redirect-frame-focus frame &optional focus-frame
     This function redirects focus from FRAME to FOCUS-FRAME.  This
     means that FOCUS-FRAME will receive subsequent keystrokes and
     events intended for FRAME.  After such an event, the value of
     `last-event-frame' will be FOCUS-FRAME.  Also, switch-frame events
     specifying FRAME will instead select FOCUS-FRAME.

     If FOCUS-FRAME is omitted or `nil', that cancels any existing
     redirection for FRAME, which therefore once again receives its own
     events.

     One use of focus redirection is for frames that don't have
     minibuffers.  These frames use minibuffers on other frames.
     Activating a minibuffer on another frame redirects focus to that
     frame.  This puts the focus on the minibuffer's frame, where it
     belongs, even though the mouse remains in the frame that activated
     the minibuffer.

     Selecting a frame can also change focus redirections.  Selecting
     frame `bar', when `foo' had been selected, changes any redirections
     pointing to `foo' so that they point to `bar' instead.  This
     allows focus redirection to work properly when the user switches
     from one frame to another using `select-window'.

     This means that a frame whose focus is redirected to itself is
     treated differently from a frame whose focus is not redirected.
     `select-frame' affects the former but not the latter.

     The redirection lasts until `redirect-frame-focus' is called to
     change it.

 -- User Option: focus-follows-mouse
     This option is how you inform Emacs whether the window manager
     transfers focus when the user moves the mouse.  Non-`nil' says
     that it does.  When this is so, the command `other-frame' moves
     the mouse to a position consistent with the new selected frame.



Local Variables:
coding: iso-8859-1
End:
